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.
A major goal of 18.1 is to upgrade to the latest versions of JET (4.2.0), jQuery (3.1.1), and jQuery UI (1.12.0 – not the latest but what JET uses). The exact versions may change before the 18.1 release is final. The time and effort involved for APEX to uptake these new versions was about what I expected and I believe we made the right decision not to squeeze it into 5.1. There were a number of little fixes needed here and there throughout the code. I happily don’t remember most of them and wouldn’t want to bore you with the details anyway. Collectively it was a fair amount of work. One thing that helped was having unit tests for some of our JavaScript code. I have been motivating us to add more unit tests since APEX 5.0. The unit tests were updated to use the new libraries and run so any failures could be investigated and fixed before switching APEX over to the new versions.
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.
The next most common (based on questions I see on the APEX forum) customization that breaks is check boxes for selecting nodes. Because of this we added checkbox selection support in 18.1. This is an advanced JavaScript configuration option. It is important to note that there are two types of selection in a tree. One where nodes are selected independently and one where the hierarchy is considered; where checking a parent node selects all of the decedents. Both types are valid, it depends on your use case. The treeView widget currently only supports independent selection as it always has. The type of selection is independent of having a checkbox but often associated with it and hierarchy selection is visually represented with a tri-state checkbox. The treeView widget API will be documented in 18.1 and this will help with porting more advanced customizations. You can take a look at preliminary documentation from the Early Adopter site. I hope to provide more treeView information and examples in the future.
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:
#JQUERYUI_DIRECTORY#ui/widgets/#MIN_DIRECTORY#tabs#MIN#.js
You should also check out the jQuery UI upgrade guides for 1.12 and 1.11 to see if there are any changes that affect your custom code.
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.
- Move CSS and JavaScript into static application or workspace files.
- 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.
- Don’t put CSS rules or JavaScript code into regions or region templates. There are specific attributes for these things. Page, List, Report, and Region templates now have attributes for JavaScript code and CSS rules as well as File URLs. Pages also have attributes for JavaScript and CSS.
- Don’t put CSS or JavaScript file URLs (link or script elements) in regions or templates. In addition to the previous tip see Shared Components > User Interface Attributes > Desktop for a place to put application global CSS and JavaScript file URLs.
- 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 triggerapexrefreshevent at the region element (only works for regions that support refresh). The newapex.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). - Remove the use of legacy APIs. Uncheck all the checkboxes for attribute Include Deprecated or Desupported Javascript Functions on the User Interface Details page. This will make your app lighter because of fewer files to load.
- 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.