Skip to Main Content

Migration Guides

Overview

You can easily update your application to use the latest version of Universal Theme and keep current with the latest features, enhancements and bug fixes. Simply follow the steps outlined on this page to get your application's theme refreshed.

Backup Reminder

Before you begin, please create a backup of your application. You can do this by exporting your application, or by creating a copy of it.

Refresh Universal Theme

Starting from Universal Theme 21.2

Your application will need to use Compatibility Mode 21.2 or higher to be eligible for Universal Theme update. To adjust the application compatibility mode, go to Shared Components - Edit Application Definition and change the compatibility mode to 21.2 or higher.

How to Refresh

First, you will need to refresh Universal Theme in your application so it is updated to the most current version.

  1. Navigate to Shared Components → Themes
  2. Verify that the Subscribed From column for Universal Theme says Theme Repository
  3. Click on Universal Theme
  4. Click Verify in the Theme Subscription region header
  5. Click Verify in the Verify Theme Subscription Dialog
  6. Click Refresh Theme
  7. Click OK

Re-apply your Theme Style

Once you refresh Universal Theme, the current theme style for your application will be reset to Vita.

If your application was using a custom theme style, please follow these steps to set your custom theme style as current:

  1. Run your application
  2. Open Theme Roller from the Developer Toolbar
  3. Select your custom theme style from the Style select list
  4. Click Save
  5. Click Save again in the Save confirmation dialog, then click OK
  6. In Theme Roller, click Set as Current, then click OK
  7. Close Theme Roller

NOTE: It is crucial that you re-save your custom theme style. This is necessary because Theme Roller will need to re-compile the css based upon the latest changes to the underlying theme.

That's it. Your custom theme style has been re-applied to your application and set as the current theme style.

Restoring Subscription

Lost Subscriptions

It is recommended that Universal Theme remain subscribed so that you can easily refresh it to receive updates upon new releases of APEX. If for some reason your application was unsubscribed or unlocked, you can restore the subscription by following these steps.

Follow these steps to restore the Universal Theme subscription and refresh it based on the latest release.

NOTE: You will lose any changes or customizations made to templates within Universal Theme.

  1. Navigate to Shared Components → Themes
  2. Verify that the Subscribed From column for Universal Theme says Theme Repository
  3. Click on Restore Theme Subscription from the side bar.
  4. Set Theme Source to Oracle Theme
  5. Set Master Theme to 42. Universal Theme
  6. Set Match Template to By Template Identifier
  7. Click Restore Subscription

This process will refresh the Universal Theme in your application based on master copy from the release of APEX. Your theme style will also be reset to Vita. If you were using a custom theme stle, you can follow the steps outlined above to re-apply your custom theme style.

Migrating from Other Themes

This guide will cover the steps involved in migrating to the Universal Theme. It will cover the pros and cons of Universal Theme, and how to go 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 Oracle APEX fundamentals.

Creating the Theme

To create Universal Theme in your application, go to 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.

Switching the 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 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.

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.

It 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.

Installation: Drag the link below into your bookmarks bar:

Universal Theme Migration Helper V1.1
Version Date Changes
1.1 6/19/15 Theme 21, 22, 23 support
Internet Explorer Support.
Auto Updating
1.01 5/13/15 Firefox Support
1.0 Initial Release

Usage: On Switch Theme page, click on the bookmarklet 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, 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.

Post Migration

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.

  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.