The last part of my APEX 5 migrations series:- APEX 5 Migration - Part 1 - Requirements and Installation
- APEX 5 Migration - Part 2 - Common application issues after the migration
This part is about the best and hardest migration:
The Universal Theme migration (UT)!
Most of the developers love the new theme and its functionality but what makes it so different to the old ones? What is the value of the extra costs for the UT migration? Which rules should be followed? And what are the most common problems you will have to face?
A. What makes the new Universal Theme (UT) so precious?
The new APEX theme standard:
Means that the UT will be upgraded in the future APEX versions and this includes your UT applications as well. This comes in handy in the following situations:
- Problems in new browser versions (i.e. Microsoft IE) will be handled by the APEX team.
- The APEX team will integrate new theme based web standards or features (i.e. flat design).
IMHO: If you have already wishes you would like to add inside the UT then just add your own feature request here: Oracle Application Express Feature Requests
APEX template options
APEX 5 brought us the new APEX template features. These features makes it a lot easier to configure templates. The UT uses those features. The only other theme I know of which uses them too is the Material Design Theme.
Newest web standards
The UT brings us a full responsive layout using the newest standards of web technology.
The UT can be used "out of the box" with laptops, tablets and mobile phones. You will not necessarily need extra mobile themes anymore.
The UT comes with a flat design and uses by default parts of the Font Awesome library which came with APEX 5.
For example: the navigation area.
TIP: All packaged applications are now running with UT. Including lots of examples, plugins and code snippets only made for you to discover and use.
Layout customization (cooperate identity)
The new UT brings two new features which will let you easily update layout functionalities:
- Theme Roller
- Navigation
Theme Roller
With the new "Theme Roller" you can style your application during the runtime and see all changes live. Design is still the same but in a new color shape. The Theme Roller can be accessed when you run the application as a developer.
More information about the Theme Roller can be found here:
APEX documentation > Using Theme Roller
Navigation
To change the way the navigation in your application works. The APEX team made some major changes in APEX 5. You can now easily change the way to navigate (tabs, left side or right side) inside the UT. To get some inspiration look at the examples provided in the UT example application provided by the APEX team.
The standard features are not enough
The last two described features are quite easily done. But what is when you need an exact visualization of your "Cooperate Identity"? This is one of the major problems you will have to deal with when you are using the UT which we currently don't have an easy solution for.
IMHO: Create a custom CSS file including all CSS changes you need. Add this file behind the standard UT CSS files.
If you still encounter problems which cannot be fixed with a simple CSS code. I propose to live with it. The alternative would be an own theme and it is not to be recommended.
B. Basic rules you should follow when you plan to upgrade to UT
1. Make a backup of your application because an UT upgrade can't be undone without a complex recovery
2. Use the APEX UT Migration Guide which provides a step by step upgrade help.
3. Try several upgrade options to find the best way for your application.
4. Don't create a copy of the UT theme itself. Because the copied version will not be upgraded in future versions
C. The most common problems after you installed the UT.
1. Label Column Span error message
This error may occure in almost every form page. To minimize the occurrence of this error try rule 3 in section "B. Basic rules".If you cannot avoid it then at least I have good and bad news for you:
- It can easily be fixed
- but it can take a lot of time
INFO: Sven Weller wrote on his blog an article "Apex 5 Upgrade – correct colspan error" about this issue and how you can handle it.
2. Grid layout
One of the biggest problems I discovered is that the item orientation often doesn't fit like you had it in your old application. That means you have to manually fix the orientation and this takes, comparing to the other parts, a lot of time.
Before the upgrade
After the upgrade
And after some fixes
INFO: Depending on the layout of your application and the mobile usage. You may have to integrate some CSS media queries to get the perfect user experience.
3. Navigation Menu
The UT don't uses tabs anymore. In APEX 5 all navigation logic is made with the new "Navigation Menu".
There is an automatic migration of all your old tabs to the navigation menu. But you probably have to adjust it a bit:
- Check if all entries exist
- Check the parent-child logic
- Check for old disabled elements
- Check for authorization schemes
4. Remove obsolete elements
Here we have to face two aspects.
- Delete old visual elements you created for the old theme
A lot of elements were created just to adjust the application appearance. Now you will not need them anymore or even worse they destroy the visual appearance in your new UT application.
- Delete old unnecessary elements
Here I refer to the old pages and regions you just hold on to because you thought you might need them in the future versions of your application again.
Now as you make a minor upgrade to your application then please remove those old components too.
Those are the elements which could be affected:
- Pages
- Regions
- Items
- HTML code
- Shared Components (Images, Plugins, Application Items, ...)
5. Custom Javascript Code (JS)
Here we face a problem which mostly occur in older APEX versions (2 and 3). In those old times :) we didn't have Dynamic Actions and because of that we had to develop all JS code manually. Now it is a good time to change this old code and upgrade it to Dynamic Actions.
Here is one example showing a modal dialog region manually created with JS. With the declarative functionality of APEX 5 in the UT you can do this much easier.
Same example just with plugins. Some of them wont be necessary anymore and should be removed.
6. Custom CSS code
The CSS part is similar to the problem I described in point 4.
A lot of the APEX developers don't have their focus on the CSS technology. Therefore we created a lot of small CSS snippets everywhere just to make the application look nicer. Unfortunately for this inaccuracy and laziness we now have to pay the price.
After the upgrade you may find lot's of obsolete old CSS snippets everywhere in your application. Each snippet can destroy the appearance of the UT application.
My guess: Because we have the advantage of the UT we don't need 90% of those snippets anymore.
Here a simple example where I used some CSS code on a cancel button:
7. Breadcrumbs
Seems irrelevant but in my mind the breadcrumbs are different now. They are not only a navigation help anymore. In UT they are much larger then in the old themes. Which means they are now more like a page headline. I think this is good but it may create some problems.
Example:
If your breadcrumb text is meaningless then nobody noticed it, written in the old version. In UT people will!
What if you haven't used breadcrumbs at all because in the old theme it didn't make so much sense?
I would say you should add them now.
8. Label alignment Above
Maybe it was a bug in 5.0.1 or it had to do with the theme I used. But after the migration to UT all item labels were not above anymore. I had to change it in the region attributes.
9. Login Page
You may have to consider to update your login page. Dimitri Gielis created a really handy example "APEX 5.0: pimping the Login page" about how to do it.
D. Conclusion
Is an upgrade as useful as everyone says?
IMHO: Yes, if you have the time or the money to do it. The advantages I described are worth the effort. Especially if you want your applications prepared for the future.
What makes more sense UT upgrade or redevelopment?
My guess is that the UT upgrade works in 90-95 % of all applications. The special ones need to be redeveloped in UT because they are to big, unsecure or using to much old techniques.
Which applications are easiest to migrate?
Reporting applications are the easiest ones.
Which applications are the hardest to migrate?
Application with form pages including a lot of custom JS and CSS code.
That's it! I hope I could give you some inspiration about the APEX 5 migration.
