Migration Guide

Transitioning to Universal Theme

This guide shows how to convert to the Universal Theme in Application Express 5. It will cover the pros and cons of Universal Theme, and how to go through through the Theme Switch wizard. This guide also covers the post-migration phase: the immediate tasks, some best practices for working with Universal Theme, and a list of common problems and solutions encountered during and after the upgrade. Please note that this guide assumes you have a working knowledge of Application Express fundamentals.

If you would like to jump straight to the template mapping bookmarklet, please click here.

Why should I migrate to Universal Theme?

Universal Theme has a number of new features, improvements, and optimizations when compared to themes provided with previous releases of Application Express. Additionally, Universal Theme utilizes several key UI features of Application Express 5 and provides a number of new Templates and Template Options that greatly expand the customizability of your application's UI.

Universal Theme provides improvements in almost every facet of defining the User Interface of your applications, and there a number of reasons why it is important to migrate to it immediately. However, you must first understand your users and see whether a drastic change in User Interface is appropriate.

Below is a quick fact-by-fact look at the many reasons for why you should migrate, and the few reasons why you may not want to migrate to Universal Theme.

Pros

Improvements

  • Cleaner Templates

    Universal Theme has fewer, but more capable templates which can be customized with Template Options. It is quicker and easier to modify the presentation by changing Template Options, rather than by having to select a new template. Template Options allow for additional visual flourishes and, in some cases, new functionality.

  • Improved Grid Support and Responsive Behavior

    Theme 25 introduced Grid Layout support in APEX 4.2, but used a fixed grid which was not easily customizable. Universal Theme introduces a flexible, fluid grid system which can be nested many times over, and is based off the Bootstrap grid.

  • Mobile Ready

    Because of Universal Theme's improved grid support, applications are responsive out-of-the-box. Therefore, they run well on any mobile device running a modern browser. For example, you will notice that tapping is significantly sped up (no delay in clicking) in Universal Theme apps compared with legacy ones.

  • Future-proofing

    While legacy and older themes are supported in APEX 5, Universal Theme is the primary theme. With future releases of Application Express you will be be able to readily upgrade the Universal Theme to take advantages of the new functionality provided. Migrating to Universal Theme is a simple means of ensuring your apps provide the most modern and up-to-date user experience for your users.

New Features

  • Theme Roller

    Older themes required you to to stick with one color and one set of styling. The only means of having your own styling was to override the defaults with CSS or switch to a new theme entirely. Universal Theme addresses this pain point by allowing you to quickly generate a new style for your app, using a GUI.

  • Navigation Lists

    In Universal theme, you now have the choice between using a top or side navigation menu. Older themes only supported tabs, which always consumed vertical screen real estate. Placing the menu on the side, and allowing it to be collapdsed, works better for most applications, especially when displayed on widescreen monitors.

  • New UI Components

    Universal Theme has built-in templates for a variety of common UI components which are not available in other themes. For example, there are templates for easily creating carousels, tabs, menus, cards, and much more.

  • Maximize/Restore

    Universal Theme enables Interactive Reports, Classic Reports, and Standard Regions to be "maximized". With the maximize button template option enabled, end users can now focus on a single region, and scroll through large amounts of data without seeing other content on the page. This makes it far easier for end users to review these large regions which are often very wide and long. Older themes do not have support for this feature.

Cons

Because migrating to Universal Theme, from older themes, will take development effort and significant time reviewing migrated pages, you should consider the downsides of migrating before moving forward.

  • Different UI.

    While Universal Theme is designed to be fully accessible and aesthetically pleasing, users who are completely comfortable with the older theme's UI, may not immediately like the new theme. Further, training material developed in-house will need to be upgraded as the look of the pages will undoubtedly change significantly.

    This is not a technical issue, since Universal Theme is not a departure from the traditional APEX workflow, but an enhancement on top of your existing processes. Application content, such as pages, regions, buttons, and items, will not be changed as a result of migrating, other than their appearance.

  • Regressions

    Some templates carried over from previous themes may not have strict one-to-one equivalents. Some of your custom CSS/JS modifications that were not directly supported in APEX may also no longer work as expected on your pages. These and other issues are covered in Post-Migration Tasks, Best Practices, and Common Issues After Upgrading sections below.

  • Custom Themes / Templates

    If you have developed a completely custom theme, then migrating to Universal Theme may require significant effort. Similarly, if you defined custom templates then you may find difficulties finding a similar template in the Universal Theme. However, you may find using the new template options and theme roller will make many of your customizations redundant. If not, you will need to manually define custom templates and reapply your custom CSS and HTML post-migration.

How do I migrate to Universal Theme?

Before beginning the migration process, it is strongly recommended to take an export of your application. This will enable you to easily revert back to the original application if necessary, before making any changes to your application and its metadata. Once you have migrated to the Universal Theme, you can not easily switch it back to the original legacy theme. Additionally, if you re-import the original application, under a different Application ID, you can refer to this application to review how the application looked previously, as opposed to how it looks using the Universal Theme.

If you haven't done so already, you should use the Application Utilities > Upgrade Application to update certain built-in widgets in your legacy applications to the latest provided by APEX 5, e.g. FlashChart to AnyChart . This will ensure that those widgets take full advantage of the responsiveness of Universal Theme.

First: Create Universal Theme in your application

From Shared Components, click on Themes and follow the steps below:

Note: If you have already installed the Universal THeme into your application proceed to the second step, Switch to Universal Theme.

  1. Click Create Theme

    You need to install the Universal Theme into your application to get started.

  2. Select From the Repository.

  3. Select Desktop as the User Interface.

  4. Choose Standard Themes as the Theme Type, and Universal Theme (Theme 42) as the Theme.

  5. Review your changes and click Create.

Second: Switch to Universal Theme.

Note: Not until you have completed Step 4 below will your application be irreversibly changed. Reverting back to a Tab-based application will be very difficult, which is why it is strongly recommended you have a backup of the application before proceeding further.

  1. Click Switch Theme

  2. Select the current desktop theme, and then select 42. Universal Theme.

    Depending on your application, you may choose to set the Reset Grid option to either Reset fixed region positions or Reset all region and item grid positions.

    Reset fixed region positions will maintain your current region positions, where possible, during migration. This is the recommended approach.

    Reset all region and item grid positions will ensure item and region positioning will be reset and will force regions and items to stack on top of each other.

    Make sure that Map Template Classes is set to No

    Press Next to continue.

  3. Verify that the mappings for your templates and Universal Theme templates are correct. Use the Universal Theme Migration Bookmarklet helper below, to automatically assign the right mapping, or check out the full mapping guide located at the end of this guide.

    Most of the inconsistencies will be from new templates that Universal theme provides. Try to choose the template that best matches your existing template. You may want to browse the components in the Universal Theme Sample Application to get a sense of the new templates and their various configurations.

  4. Click Switch Theme.

Final steps: Post migration tasks

Unlike the previous steps, the following tasks do not have to be completed in any particular order. Instead, it is advised that you carry them out before making new enhancements to your application, to ensure that any issues relating to the migration are not complicated by changes in functionality.

  • While it is not necessary to remove your older theme for your freshly migrated app to work, your older theme no longer serves any functional purpose. If you haven't created any custom templates in your older theme (which you'd want to copy over), or if you don't need to keep the older theme for reference, consider deleting the older theme.

  • Ensure that the list items for Navigation Menu are correct, and that the Current For attributes are properly set.

    Your tabs will be converted into a list format. If the current for attributes are not set correctly, the navigation links will not be selected when you navigate to each of the pages.

  • Decide if you want to stick with Side Navigation or change to the Top Menu as the application's primary means of navigation.

    If you choose to stick with side navigation, it is recommended to select Navigation Icons for each menu entry, otherwise each page will have the same default page icon. By going to Shared Components > Navigation Menu > List Entry, you can choose from a variety of pre-built icons, allowing you to choose the best match for each page type. Please note that these icons will only appear if you are using side navigagtion.

    To change to Top Menu you will need to navigate to Shared Component > User Interface Attributes > Edit Universal Theme. Then change Position to Top and List Template to Top Menu Navigation, and then apply changes.

Best Practices for managing post-migration issues

While most migrations will be relatively painless, there is no set path for how dealing with issues arise as a result of this change. Consider the following pointers for how to exhaustively find and resolve such problems in your new Universal Theme Application.

  1. Visually review the migrated application.
    - Run each page of your application, or at least a good cross section of different pages to make sure that there are no obvious display issues.
    - If you have installed your original application under a different Application Id, perform side-by-side comparisons on a wide selection of pages, to ensure different page elements, such as buttons, and the overall page layout are not too divergent.
  2. Check non-standard components.
    - Be sure to check any pages where you implemented your own JavaScript to ensure the page still operates correctly. Many of the default class names for elements were changed, and some of the inline scripts that you have augmented your pages with may no longer be needed.
    - Review any pages or templates where you have added any CSS libraries. If necessary, reapply the CSS libraries into the migrated application.
    - Review all plug-ins used throughout your application to ensure they are still functioning correctly. Some plug-ins from third parties may not work correctly with Application Express 5. If so, you may need to remove the plug-in or search for an APEX 5.0 compatible plug-in.
  3. Ask your users to test your app.
    - After testing the application yourself, the next step is to ask your users to use the new migrated application to ensure they are comfortable with the new user interface, and can readily use the application.
    - Determine from your end users if any end user training material or application documentation needs to be revised before releasing the new application into production.

After Debugging

Once you have brought your application up to a "functional" state, you should consider a few more simple improvements you can readily make to your application, so that you can take full advantage of the new features in both Application Express 5 and Universal Theme. For example, you may want to prototype some different layout options, with a select group of users, to see if existing pages can be readily improved by simply changing some Template Options.

Bookmarklet

There is not always an equivalent template in Universal Theme for all templates from previous themes. For this reason, the APEX Development Team has created a bookmarklet to assist you with mapping your older templates to your newer templates in the Verify Compatibility step of the Switch Theme wizard.

The Universal Theme Migration bookmarklet supports mappings from the 3 most popular legacy themes, Theme 24, 25, and 26. It also supports any themes that are based off these legacy themes, i.e.: if your theme was based on one of those themes. When utilized then the bookmarklet will do most of the mappings correctly to produce the best results from the migration.

To install the bookmarklet, drag the bookmark into your bookmarks bar.

Then, on the Verify Compatibility page, where you perform the template mappings, click on the Universal Theme Migration bookmarklet to attempt to update the template mappings. If the theme you are migrating from is supported, then it will automatically match the templates of your older theme to the correct templates in Universal Theme.

If your theme is mapped properly, each of the select list values that were successfully altered will be highlighted in green.

Once the mapping process has completed, any errors you encounter will be displayed On an error page. You can try clicking on the Map to a Different Theme button, to try re-mapping with an alternate theme available within the book marklet. If the expected mapping can not be found in the select list for that template, then it will be highlighted in orange.

Typically receiving any errors either means your custom templates did not strictly match the theme you chose, or that you have not set Match Template Classes to "No" in the previous step.

Frequently Asked Questions

When Upgrading

  • Problem

    Warning: You must have at least two themes installed to be able to switch. Please create a new theme and attempt this action again.

    Solution

    Create the Universal Theme in your application, as outlined above, before trying to switch your theme. Please start the guide from step #1.

  • Problem

    This application cannot be converted to a theme using list-based navigation, as it uses two levels of tabs. Please update the application and set current tabs settings to use only one level of tabs prior to switching the theme. (Go to error)

    Solution

    Because two-level tabs are not supported in Universal Theme, you must re-design your existing apps to use only one level of tabs, and then switch. If doing so proves too complicated, try deleting the parent tabs, conducting the theme switch, and then re-creating navigation using a navigation menu post. To delete the parent tabs, you must go to "Shared Components > Tabs > Edit Tabs > Manage Parent Tabs " and click on each of the parent tabs to access the button to delete them.

After Upgrading

  • Problem

    When running my app on a certain page, I get the error message "Label column span grid setting for this page item is invalid."

    Solution

    In this example, with a label column span of 3 plus each item's column span of 1, all 4 together means that the content is 16 columns wide. This exceeds the 12 columns supported by the Universal Theme which results in this error being thrown before the page is rendered in your browser. To Fix: navigate to the page item specified in the error message in page designer or component view, and reduce the number of label column spans that your elements consume.

  • Problem

    My content is no longer placed in multiple columns

    Solution

    If you reset all the grid positions that your app previously used, then your content will be placed in one column after upgrading. To recreate the columned layout you had before, just drag the regions into new columns with Page Designer.

    You can also "fine-tune" the grid and column spans using the right side bar to get a layout that resembles your original theme.

  • Problem

    My navigation bar is not a list

    Solution

    In order to add menus and have fine grain control of your Navigation Bar, i.e., your upper right hand corner links, it will need to be converted from the "Classic" implementation to a "List" based one. To do so, you must first create a new list which contains entries such as your user name (APEX_PUBLIC_ROUTER), a sign out link, and any other app-wide links you would like to have. Once this list is created, navigate to "Shared Components -> User Interface Attributes -> Edit Desktop -> Navigation Bar" and change the Implementation from "Classic" to "List". "Select the List you created earlier, and set List Template to Navigation Bar". Your app will now be using a list-based navigation bar. With a list-based Navigation Bar, you can then add sub-entries which will appear in a drop down menu.

More information

If for whatever reason this guide fails in providing adequate assistance, please reach out to us on the Oracle Technology Network (OTN) discussion forum or on Twitter (#orclapex). Any specific problem you have is likely to be encountered by others. Notifying us will help to improve this guide with additional information and facts relating to Universal Theme migration.