Handling jQuery Migration in Mature Applications

I’d been working with mature code and had to migrate many web pages in multiple projects from older versions of jQuery to the “most recent”.

This was a blast from the past.

This short guide documents the main steps, typical errors, examples and fixes you can expect to take and find

In general, upgrading involves the following steps (source):

1. If jQuery version < 1.12.4, upgrade to 12.4 or 2.2.4 (depending on what version is presently being used) and include the jQuery 1.x migrate plugin.
2. Test and resolve any found issues from the 1.x migrate plugin.
3. Remove the migrate plugin and verify pages still work.
4. Upgrade jQuery to the latest 3.x version and include the 3.x migrate plugin.
5. Repeat the testing process and resolve any issues brought up by the 3.x migrate plugin.
6. Remove the 3.x migrate plugin and make sure the pages still work.

Note: To upgrade to jQuery 3.0, you first need version 1.12.x or 2.2.x. If you’re using an older version, first upgrade to one of these versions using jQuery Migrate 1.x, to resolve any compatibility issues.

Identifying the Errors

After installing a migrate plugin, work through each page you need to test for compatibility during the migration.

For example, this button click even wont work with the version of jQuery being references:

The Migrate plugin surfaces errors in the console.  To find them, open the browser debugger for the page and locate the error:

If the error is in an externally reference JS file, locate the “anonymous” link, and click on the filename:

In this example, pen.js:

You can then update the older script to use the new event/code.

Typical Errors and Fixes

The typical errors I found are included. Each has an example and the example fix.

JQMIGRATE: jQuery.fn.toggle(handler, handler…) is deprecated

Cause: There are two completely different meanings for the .toggle() method. The use of .toggle() to show or hide elements is not affected. The use of .toggle() as a specialized click handler was deprecated in 1.8 and removed in 1.9.

Solution: Rewrite the code that depends on $().toggle(), use the minified production version of the jQuery Migrate plugin to provide the functionality, or extract the $().toggle() method from the plugin’s source and use it in the application.

Example:

$(".help > footer").toggle(

// DO STUFF

});

Fix:

Implement a custom function and use that:

    $.fn.toggleClick = function () {

        var functions = arguments,

            iteration = 0;

        return this.on("click", function () {

            functions[iteration].call();

            iteration = (iteration + 1) % functions.length;

        });

    }


    $(".help > footer").toggleClick(

// DO STUFF

});

JQMIGRATE: jQuery.trim is deprecated; use String.prototype.trim

Cause: Older versions of IE & Android Browser didn’t implement a method to trim strings so jQuery provided a cross-browser implementation. The browsers supported by jQuery 3.0 all provide a standard method for this purpose.

Solution: Replace any calls to jQuery.trim( text ) with text.trim() if you know text is a string; otherwise, you can replace it with String.prototype.trim.call( text == null ? “” : text ).

Example:

var cookie = jQuery.trim(cookies[i]);

Fix:

var cookie = String.prototype.trim.call(cookies[i] == null ? "" : cookies[i]);

JQMIGRATE: jQuery.fn.click() event shorthand is deprecated

Example :

$('input[name="control_name"]').click(function () {

Fix :

$('input[name=" control_name "]').on("click", function () {

JQMIGRATE: jQuery.fn.focusout() event shorthand is deprecated

Example:

$('#control_name').focusout(function () {

      // do stuff

});

Fix :

$('# control_name').on("focusout", function () {

jQuery.fn.focus() event shorthand is deprecated

Example :

var inp = $('.focus:last').val();

    if (inp != null) {

        $("#" + inp + "").focus();

}

Fix :

var inp = $('.focus:last').val();

    if (inp != null) {

        $("#" + inp + "").trigger("focus");

}

Summary

Most were similar fixes but some required a little coding. Sometimes  you are down at the cutting edge of development, sometimes you have to pay back a little technical debt.

Both are valuable experiences.