Note this is about a future release of APEX and the final release may differ from what I describe.
You’ve read the announcements, you’ve seen the presentations, you signed up for the early adopter, and gave feedback and now you think there is nothing to do but sit back and wait for 18.1 to be released – no no no. In this article I will tell you what you need to do to prepare for the jQuery, jQuery UI, and JET library upgrades in the upcoming APEX 18.1 release (was 5.2). This applies to apps and plug-ins. If you wrote an APEX plug-in that you have shared with others be proactive and make sure it is ready for 18.1.
For charts we hitched our wagon to Oracle JET starting in APEX release 5.1 and this was a very good decision. The JET data visualizations look great and are of high quality. Late in our release cycle JET released a new version that required newer versions of jQuery and jQuery UI. At that time we could not upgrade to the latest JET release because we could not upgrade jQuery without taking time to update our code to work with these newer versions and we could not risking destabilizing APEX or breaking customer’s apps (jQuery was a major version update with breaking changes). JET being a new library is moving very quickly. When 5.1 came out people wanted to use the latest JET but APEX was stuck using an older version.
For all the built-in functionality of APEX, the builder, native components, and packaged apps we have made all the necessary changes needed by the library upgrades. If your apps stick to the built-in APEX components and declarative features then the move to APEX 18.1 should go smoothly. If you have any custom client side code including 3rd party libraries or plug-ins then keep reading to find out what you may need to do.
When jQuery changed from version 1.x to 2.x there were breaking changes and the jQuery Migrate plugin provided backward compatibility. APEX 5.0 added the option to include the migrate plugin so that apps relying on old jQuery code would still work. Moving from jQuery 2.x to 3.x also has breaking changes and again there is a jQuery Migrate plugin but this is a new one that does not include the 1.x to 2.x fix-ups and cannot work in combination with the previous migrate plugin. APEX 18.1 has removed the old 1.4.1 migrate plugin and replaced it with the 3.0.0 one. When you say yes to Including jQuery Migrate you get the new one that works for the 2.x line of jQuery. APEX can no longer support the 1.x jQuery features that were removed in the 2.x line (actually it was version 1.9 where the breaking changes began. I have been using 2.x to keep things simple). APEX can only support 2.x features that were removed in the 3.x line by using the new jQuery Migrate plug-in.
The 5.1 release notes let you know that old jQuery versions are deprecated and the 18.1 release notes will tell you about the changes related to these library upgrades but I will try to state it more plainly:
If your APEX app requires the Include jQuery Migrate attribute (on the User Interface Details page) to be Yes then your app will not work when upgraded to APEX 5.2. You must update your app to work with jQuery 2.2.x; you can start this work now. You should update your app to work with jQuery 3.1.x. Just because your app has jQuery Migrate set to No already doesn’t mean you have nothing to worry about, keep reading for more information about using jQuery UI widgets, JET, and the Tree region.
Keep in mind that it could be code that you have written or code in a 3rd party plug-in or library that is affected by breaking changes in jQuery. For plug-ins or libraries see if there is a newer version. If you have code that uses 1.x removed functionality see this upgrade guide. If you have code that uses 2.x removed functionality see this guide.
Start by running your app with the browser’s developer tools console window open. Look for messages logged by jQuery Migrate. These will tell you what needs to be changed. When all issues have been addressed and there are no more messages then you can set the Include jQuery Migrate attribute to No.
After you have turned off jQuery Migrate you may find that it is still loaded on some pages. This happens automatically when you use the Text Field with autocomplete item or the Tree region using the deprecated jsTree implementation.
If you are using the Text Field with autocomplete there is nothing you need to do. In 18.1 we have a replacement implementation based on JET ojInputSearch widget that is fully backward compatible (for all declarative features).
If you are using the Tree region with the deprecated jsTree implementation then you may have some breaking changes to fix. The jsTree library is incompatible with the new jQuery library and had to be removed. On upgrade any Tree regions will be automatically switched to use the APEX treeView widget implementation. The most common thing to break is tree node icons. I have previously given instructions on how to update the icons.
If your APEX app uses other jQuery UI widgets such as tabs or accordion it will not work because the new version of jQuery UI has changed the names and locations of its files. APEX automatically loads a custom bundle of jQuery UI, named
jquery-ui-apex[.min].js as part of
desktop[_all].min.js, that includes all the core modules, the mouse interactions, button, checkboxradio, controlgroup, datepicker, dialog, and tooltip widgets and their dependencies, and the drop effect. If you previously loaded the sortable interaction widget file you can remove it as it is now included in the standard APEX bundle. Currently the jQuery UI CSS file automatically loaded by APEX includes all the jQuery UI modules. Don’t rely on this being true in the future because I hope we will optimize our CSS to be smaller and this includes 3rd party libraries.
If your app uses any other jQuery UI widget you will need to update the path to the file. For example the correct way to reference the tabs widget is:
If you have added any custom JET code, such as dynamic interactions with APEX Chart regions or perhaps your own JET widget plug-ins, then you need to check out what has changed in JET. There have been many releases between JET 2.0.2 that shipped with APEX 5.1 and JET 4.2 in APEX 18.1. Start with the latest release notes and work your way back.
The other big consequence of upgrading versions is the Mobile User Interface based on jQuery Mobile is deprecated. In 18.1 existing mobile apps still work because we ship old versions of jQuery and jQuery UI just for jQuery Mobile. Don’t use these old versions for anything else.
Don’t just make your apps work make them work better. Many of the apps impacted by this upgrade are very old. They have been working through many upgrades because of the efforts of APEX and the libraries we use to provide backward compatibility. But things change rapidly in the web development world. Backward compatibility needs to be balanced with shedding the baggage needed by old browsers, no longer supported and taking advantage of new browser features. At the same time many improvements have been made to APEX in the area of client side customizations. This is a good time to make sure you are using the latest APEX best practices. Here are some tips:
- Consider migrating to the Universal Theme.
- Create minified versions of your files. If you have multiple files combine them and use the concatenated file feature found on the User Interface Details page.
- Make your customization modular by making it a plug-in.
- Do use
#JQUERYUI_DIRECTORY#to reference jQuery UI files but be aware that files have moved around since the release that shipped with 5.1.
- Review the latest APEX API documentation to see if there are simpler ways to do what you are doing. Just a few examples: Use
apex.region(...).refreshrather than trigger
apexrefreshevent at the region element (only works for regions that support refresh). The new
apex.region(...).callmethod can save you typing and reduce the size of the code. Replace ad-hoc tooltips with jQuery UI tooltips. Replace ad-hoc dialogs with inline region dialogs (using the Inline Dialog region template).
- Keep a look out for deprecated features and APIs and proactively move away from them. Review the APEX release notes looking for deprecation notices. Look for similar information for the libraries APEX uses including jQuery, jQuery UI, and JET.
- Check for the latest version of 3rd party plug-ins you use.