I’m going to take a short break from the Hidden Gems series (more gems coming, I promise!) to talk about the process of converting applications to the new Universal Theme (I’ll call it UT for convenience) in APEX 5.0, because there are several items to watch out for in the process.
Naturally, the first question is, do I need to make the change? The short answer, of course, is no; all old applications should continue to work in APEX 5.0, regardless of the theme. The longer answer, though, is that you probably should, even if you’re using a custom theme–the HTML generated by the UT is designed to be responsive, so it’ll work on pretty much any device, as well as to be accessible, so people with screen readers & such shouldn’t have many issues with your site. And it looks more flat/modern, though whether the style is what you want is up to you. (Luckily, you can change things pretty easily–and drastically!–with the theme roller, so you’re no longer stuck with what the APEX team provides.)
Next, you need to create the UT in your application. Go to Shared Components/Themes, and hit the Create button. Just go through the wizard–the default options should lead you straight to the UT.
Once you’re back at the Theme page, it’s time to hit the Switch Theme button. This is where things get complicated, and the amount of manual work you need to do afterwards is largely dependent on getting this step right.
The first field is the “Currently Active Theme”; just select your current desktop theme. Then select the UT as the “Switch to Theme”. If you’re currently using theme 25 (or a custom theme based on it), you can leave the “Reset Grid” field alone; if you’re using any other theme, though, you’ll want to change that to “Reset fixed region positions” at least, or you’ll run into errors when you run the page complaining about trying to put multiple regions in column one. That’s a very frustrating error, since you won’t see it until you actually run the page. The final option, “Match Template Classes”, should be set to No. Really–pay attention to this one, or you’re going to be really frustrated with the next step! If you have it set to Yes, then APEX will try to only offer you templates that are from the same “class” as your existing ones. However, the classes used for different region types are likely to be changed.
The second page of the wizard, titled “Verify Compatibility”, is where the bulk of the work happens. You need to go through all of the templates used in your application and make sure they’re using appropriate templates. If you don’t see many options in some of the “To Template” drop-downs–if, for instance, the Standard Region only allows you to select the Interactive Report template–then you need to go back to the previous page and change the “Match Template Classes” option to No. Take your time on this page; it’s a lot easier to get things right here than it is to clean them up later. Trust me.
The third page of the wizard is the confirmation page, which is your last chance to bail out. Go ahead and hit the Switch Theme button.
From this point, it’s simply a matter of running your application and fixing all of the areas where something doesn’t look quite right. But if you got the template mappings correct, you should have a much easier time of it!