jQuery v3 is the lightest, fastest version of jQuery to date, removing support to IE6-8 (like the previous 2.x branch).
The upcoming Joomla v4 will come packaged with jQuery without Migrate. If you are planning on using jQuery a little bit longer, now is the time to check your scripts.
Old scripts built for earlier versions of jQuery may 'break' with jQuery v3, but thankfully, the jQuery team has provided an updated version of the Migrate plugin to help identify compatibility issues.
It is not possible to directly update old scripts with Migrate v3 alone (it does not support all accumulated changes made since jQuery v1.6), therefore the migration will have to be performed in a few steps.
Using jQuery Easy or jQuery Easy Profiles makes the process a little easier.
Step 1 Open the jQuery Easy system plugin (or a jQuery Easy Profiles module instance), go to the basic options and enable jQuery.
Step 2 Select the latest 1.x or 2.x version of jQuery (check which sub-versions are available at the Google CDN).
Step 3 Select the version 1.4.1 of jQuery Migrate.
Step 4 Set the compression in the General Options to 'uncompressed', which will make the Migrate plugin verbose (it will diagnose issues and report them by generating warnings instead of restoring deprecated features and behaviors).
Step 5 Open the browser's console and fix any problems in your scripts identified in the console by the Migrate warning messages (starting with JQMIGRATE). Check the list provided by the jQuery team to find out how the incompatibility can be solved. You may not have any warning, in which case the scripts do not require any modifications!
Step 6 Disable the Migrate plugin (set Migrate to 'none').
Step 7 Make sure the pages containing jQuery still work properly.
Step 8 Select the latest jQuery 3.x version (check which versions and sub-versions are available at the Google CDN).
Step 9 Select the latest version of Migrate v3.x.
Step 10 Check the browser's console and fix any problems in your scripts identified in the console with JQMIGRATE. Check the master list provided by the jQuery team to find out how to replace the deprecated feature. You may not have any warning!
Step 11 Disable the Migrate plugin (set Migrate to 'none').
Step 12 Make sure the pages containing jQuery still work properly.
Step 13 Set the compression in the General Options back to 'minified' to ensure your pages load faster (if you decide to keep jQuery Easy enabled).
You can skip steps 10, 11 and 12 and keep Migrate loaded on your pages when using jQuery Easy. This will ensure your scripts work properly without the need of them being fixed for jQuery v3.
Note that using Migrate v3 in conjunction with jQuery v3 will also garantie oldest versions of jQuery UI and Mobile remain fully operational.
If you decide to manually include Migrate on your website pages, you cannot use different versions of Migrate on the same page. The process cannot be reduced to fewer steps than the ones stated in this article.
Useful links
- jQuery v3.0 upgrade guide
- Migrate v3.0
- Migrate 1.x warning messages (causes and provided solutions)
- Migrate 3.x warning messages (causes and provided solutions)
