Oracle APEX Theme Update Left Me Spinning.

My experience with the ever-reliable, fantastic Oracle APEX is that it is normally ever-reliable and fantastic, but like any tool there can be a few occasions when you are left scratching your head wondering why something isn't working quite right. One such, thankfully rare, time was after updating the theme used by an application that completely prevented me from being able to update a page.

The application had been neglected for quite a few releases, I actually suspect it hadn't been updated since the move from version 4 to 5 many moons ago, so we went ahead and refreshed the theme from the master version it was subscribed to which itself was now at version 23.2.

Apart from the usual bit of TLC required to reposition some of the app's layout, in general things went well; all except this one page. The page worked fine in the application but trying to edit it in the designer was a non-starter, the spinner just sat there in true "spinning wheel of death" fashion taunting us. Displaying the browser console enlightened us to an error emanating from the JavaScript stack preventing the page from loading:

An undefined property of the "displayPoints" object sparked a quick search through the forums and we stumbled across this post which told us it was an invalid page template causing it. Really this shouldn't have been the fatal error it turned out to be, for other page-level items where the template is no longer supported, APEX simply reports that the template is invalid and shows the internal ID rather coming to a complete halt but here we are.

The solution in the aforementioned post suggests updating the data in the base WWV_FLOW_STEPS table directly with the correct ID but that assumes a) you are able to do this with your level of access as a developer and b) you are comfortable working directly with the internal Oracle APEX tables which some are not.

For those that either cannot or will not update the internal metadata directly, the alternative solution is to do the following:

  1. Export the page

    This can be done from the home screen for the application using the Export/Import option.

  2. Once exported, open the .sql file and scroll down to the call to the create_page procedure and simply comment out the parameter for p_step_template.

  3. Save the file and import it back into the application. The parameter is optional and commenting it out will force APEX to use the default page template for the new theme and, in so doing, updating the internal metadata itself.

Now the page should have no trouble loading and you can continue to work on the theme update. Hopefully in future releases of APEX, this will not be an error that prevents the designer screen from loading and rather presents the template in the same manner as any of page item.

Ironically, the older versions of APEX that allowed you to select to display the designer in the original "HTMLDB" layout that lacked all the drag and drop, JavaScript-heavy functionality, its one saving grace was that it would have loaded the page if faced with this same issue and allow you to correct the invalid page template. However, I would not trade all the lovely new functionality the current layout offers for this one small, once in a very long while inconvenience.