16Sep2019
Information
Print

Update old jQuery scripts for compatibility with jQuery 3

Information
jQuery jQuery Easy jQuery Easy Profiles
First published June 23, 2016
24251 hits -
 

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.

Enable jQuery
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).

jQuery selection
Select the latest jQuery version (v1.x or v2.x series)

Step 3 Select the version 1.4.1 of jQuery Migrate.

jQuery Migrate selection
Select Migrate v1.4.1

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).

Javascript compression
Set the compression to uncompressed

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!

Browser console with Migrate logs
Check the browser console

Step 6 Disable the Migrate plugin (set Migrate to 'none').

jQuery Migrate selection
Set the Migrate version 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).

jQuery selection
Select the latest jQuery v3 version

Step 9 Select the latest version of Migrate v3.x.

jQuery Migrate selection
Select the latest 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!

Browser console with Migrate logs
Check the browser console

Step 11 Disable the Migrate plugin (set Migrate to 'none').

jQuery Migrate selection
Set the Migrate version 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).

Javascript compression
Set the compression to minified

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