Migrate your apps to Universal Theme in APEX 5

Hi and happy to be back.

Somehow I forgot what blogging was. But constructing a house, making it your home and moving into that new home took quite some time and above all energy. So blogging didn't have my highest prio for the last couple of months.

I know, it's just excuses, but as all that is none of your interest, I'll get on with the work :-)


So, I'm preparing a demo / workshop to show people what, how and why to migrate your apps to the Universal Theme (UT) once you did the technical migration to APEX 5.

This is all very well documented by the Oracle APEX Team, fow which many many thanks!
Here's just an overview of what I needed when doing my research. I'll build up the blog post along with my prep.

Migrating to Universal Theme

What is this UT?

So what is this UT and what's all the fuss about it?

Well, these insights from my point of view, not a commercial talk, nor a high-specialist talk. But an every day APEX developer and Oracle specialist.

I believe that my profile of developer is exactly why they have developed the UT to begin with.

I was trained by Oracle in the mid-nineties. This means PL/SQL, Oracle forms, PL/SQL, Oracle Reports, PL/SQL, Designer, PL/SQL and also some PL/SQL.

I have gradually picked up some HTML knowledge. Learned to deal with XML and more recently also JSON file formats.

I've upgraded my knowledge via self-study on CSS, Javascripting and I'm following some blogs on web-design in general. I try to keep up with the latest, which is not always easy. From the web-design/development point of view: I'm an old guy.

So UT for me exactly takes away those deep technical requirements that I'm not specialised in.

Still I urge you to have some knowledge of the web development skills mentioned above. But UT will help  you a lot!

And there is one more thing I like so much about the UT: 

as developer we can come up with great ideas of what an app can/should do. We're also capable of actually building just that. But what about the design, the user interface? It's often not our strongest skill. I know it's not mine. On top of that: I'm color blind. I literaly see things differently than other people.

Now with the UT, they can build the app and don't bother too much on the color schemes. Because it can be changed once you're done developing. Or during development. There even is a Theme Roller which allows you to change colors of the objects and it picks colors that fit together. More later, but ... honestly: WAW !

Other than all that, there are a number of reasons why you should migrate to UT. Or at least try to, because there are also some down sides. But all this is well explained in the Oracle documentation.

 So my first link: The Oracle Migration Guide.

How to decide to migrate or not?

Yeah, well, good question.

You may have good reasons to oppose against UT. Perhaps you have invested a lot in your own custom theme. With lots of nice looking stuff in there that works just as you want it to.

Although perhaps UT has those customizations built-in standard, it will take an effort to match and align them. Not even having spoken about the testing efforts after migration.

UT follows the latest stuff in web design. Certainly concerning navigation it is quite a change to the old style of navigation. But what if you actually like that? Perhaps you or your users are not so keen on change?

And another important - if not the most important - reason why not to migrate: you have invested already a lot in development of the app(s) in the first place. Now you have to invest in those same apps.

Bottom line: think about these things upfront and discuss them fairly with your boss or customer.

We as developer probably all wouldn't like anything more than to migrate. Don't forget it comes with a price tag!

Backup there ... slowly, one step at the time

Of course, first backup the app you want to migrate. And also of course, I'm assuming that the technical upgrade to APEX 5 has been successfully done.

One reason to take a backup is the obvious one: it's a backup.

But I hadn't thought of a second one myself until it was pointed out to me: once you have migrated your app to the new UT, it's a good idea to import the old one (with a new APPLICATION ID) so you can run both versions at the same time. And do all your tests.

If there is something you don't like, you can start off again from the original version and migrate all over again.

Probably a good idea to run each version in another browser.

Now let's take it step by step

Basically all I'm doing here is following the steps in Oracle Migration Guide!

So it seams a bit over the top to retype those steps here. and I don't want you to think that I came up with all those steps by myself ;-)

So open that migration guide in a different window or tab and leave it open!

Therefore again: The Oracle Migration Guide.

But there are some things you need to know about your old app before you migrate.

UT is far more grid orientated then the old themes. That is, if you had already a GRID theme to begin with!

So take some time to investigate on this.

Another very important one is the TAB-levels used in your old theme. UT doesn't use tabs anymore (thank you very much!) and it the Wizard is not capable of migrating apps that have multi-level tabs.

If this is your case, then first go and adapt the original theme to one-level tabs!

Follow Oracle's guidelines on the migration when switching from old to new.

Match template classes?

The migration guide tells you to switch this option to "No", without explaining why.

So what do I do? Yup, I left it to its default ("Yes").

And it all worked out fine. I was lucky? No, I wasn't ... I just had a very simple app to start off with.

However there must be a reason why they say to switch it to "No".

And there is. It's all the next step: the mapping of the classes.

APEX will try to help you with this mapping. But when this option was set to "Yes", it will only offer templates that are from the same class as the original ones. This will often NOT be the case and you will be left with quite some frustrations when migrating the more complex apps!

So keep control and believe Oracle there ... switch it to "No"!

Map your templates tot the UT templates

Although this is just a small step as described in the guide, take your time here. You even may want to try different versions of migrations in order to find the right settings.

It will save you a lot of time if you do the correct mapping here, rather then just picking one and you're left with a whole lot of individual changes on every page of your app to correct the situation.

Here once more the backup of the original app may come in handy!

Because this is such an important step, I'm taking some more time on it:

So here is a very simple example of an app created with the Blue responsive theme 25.
UT was not created yet in this application before I started.

And this is how the working app looks like in APEX 5 without having migrated it to UT:

So I create the UT in the application.
And I start the Switch wizard.

First attempt with the Match Template Classes set to "Yes" (against Oracle's advice).

Mapping:

Note the mapping options for Standard Region:

 

This actually is a reminder for you that you have the mapping option set to "Yes". Because see what happens if you go back one step and set it to "No".

You can actually just go back here with the "<" button.

Note the mapping options for Standard Region now:

Already here you should be convinced to set that parameter to "No". Actually, it beats me why the "Yes" exists in the first place and even more why that is set as default. But that's probably just me ;-)

And now comes the nicest part of this step. the Universal Theme Migration Helper.
Today (3rd of August 2015) it's up to version 1.1 supporting themes 21, 22, 23, 24, 25 and 26.
If your custom theme is based on one of these, then certainly pay attention to this section of the migration guide.
I have now added the Bookmarklet to my bookmarks (in my case the browser is Chrome):

For the more complex apps, this will make a huge difference in the mapping proposed by APEX. In my case there's not a lot of difference as my app is a very basic example.
But adding this Bookmarklet is an easy thing to do and you need to this only once. Well, for each browser you're using in case you use multiple browsers.

And this is what it looks like in APEX 5 in Universal Theme:

My conclusion

It's all relatively easy to do. But do your homework first.

Know where you start from.

And thoroughly test your migrated apps on look and feel AND on functionality.

Mind you, now you've only done a migration. You should investigate also if you can replace some custom stuff with standard APEX 5 + UT stuff. A lot of things are in there that weren't in the old themes (or APEX version). You've just taking the effort to migrate, now is the good time to look into the app to see if you can replace/remove some custom work. I strongly believe that it's way better to stick as much as possible to the standards of APEX!

And my advice: try to migrate. It will pay off in the end.

If you have many applications - may be even linked to one another - start with one and see if it still works all together.

And then take it one by one. Keeping in mind that the user interface changes. So apps that belong together, probably need to have the same UI feeling.

Grouping your apps is never a bad idea.

Theme Roller

I promised some more on the Theme Roller.
Well, following screenshots speak for themselves. Id didn't write one single line of code. I didn't know any of the names of the colors used. I just turned the wheel ... very easy to go and find (or create) your company color scheme. And the different styles can be saved and re-applied to other apps.

Before

After(s)

I'm not pretending this color combination is a good idea! Just wanted to point out how easy it is to change it ... :-p

 And if you're still not convinced, have a look here:

Thanks for sticking with me up to here :-)
and happy to share ...