Skip to main content

Upgrading to jQuery 3.0

Overview

This guide is meant for apps on PMACS Frontend versions older than 1.4. It was written because it's important to keep our applications on current versions of jQuery so that we can benefit from, and easily apply, security patches. This upgrade is implemented using a combination of the PMACS Frontend gem, the PMACS Pickers gem, and the jQuery Migrate tool.

Furthermore, there are two parts to this migration guide: Basic and Custom. Apps that don't contain custom jQuery code will be able to upgrade following the directions in the Basic Migration section. Apps that do contain custom jQuery code will need to follow the steps in both the Basic Migration and Custom Migration sections.

Basic Migration

Gemfile Changes

Require PMACS Frontend version 1.4 in your Gemfile. The updated PMACS Pickers version 2.0 and the jquery-rails gem are managed by the PMACS Frontend gem, so they should not be in your Gemfile. Also, we highly recommend removal of the jquery-ui-rails gem, which contains severe vulnerabilities.

+ gem 'pmacs-frontend', '= 1.4.0'
- gem 'pmacs_pickers'
- gem 'jquery-rails'
- gem 'jquery-ui-rails'

About the jquery-ui-rails Gem

If you are unsure whether or not your app contains jQuery UI code, it's best to remove the jquery-ui-rails gem. If your app still needs this gem to operate, you must source it directly from the GitHub repo. There has been a recent PR merge which not only addresses an XSS vulnerability, but upgrades to the latest jQuery UI version, however, it has not yet been published to RubyGems.

JavaScript Changes

As stated before, PMACS Frontend manages many of our dependencies, including jQuery itself! Therefore, you should remove some requirements from your application.js file.

- //= require jquery
- //= require jquery-ui
- //= require jquery_ujs
- //= require pmacs_pickers
  //= require pmacs-frontend

Test jQuery Version

At this point, your app should be fully upgraded to jQuery 3.6.0. To make sure that it is, run your app locally and type jQuery.fn.jquery into the browser's console. You should get a return value of "3.6.0".

If an older version is returned, or if your app contains custom jQuery code, continue onto the Custom Migration section.

Custom Migration

Apps that contain custom jQuery code, will need to utilize the jQuery Migrate plugin as part of the upgrade process.

About the jQuery Migrate Tool

jQuery has created a handy tool to make the upgrade to 3.6.0 as easy as possible. It's called jQuery Migrate.
The jQuery Migrate plugin restores the APIs that were removed, and additionally, shows warnings in the browser's console when removed and/or deprecated APIs are used (development version of jQuery Migrate only). That way you can spot and fix what otherwise would have been errors, until you no longer need jQuery Migrate and can remove it.

Add the jQuery Migrate Plugin

Add the uncompressed jQuery Migrate 3.4.0 plugin code as a new file to your project's assets/javascripts directory. Require the new jquery-migrate-3.4.0.js file in your application.js file, making sure it's listed after PMACS Frontend, PMACS Pickers, and any other file that contains jQuery.

  //= require pmacs-frontend
  //= require pmacs_pickers
+ //= require jquery-migrate-3.4.0

Resolve jQuery Changes

Test your app and resolve any warnings that appear in the browser's console, using the JQMIGRATE 3.x warning documentation as a guide.

NOTE: All messages generated by the plugin code will start with the text "JQMIGRATE" for easy identification. Items listed as deprecated and removed must be changed before the code will work properly without the plugin code. Items listed as deprecated only are still supported by the current version but no longer considered a good practice, and may be removed in the future.

Major Changes

You can find a summary of important changes outlined at jQuery's website.

Retest jQuery Version

Remove the jquery-migrate-3.4.0.js file, as well as its respective require line from the application.js file, and ensure that the app continues to work properly with only jQuery 3.6.0 in use.

Again, run your app locally and type jQuery.fn.jquery into the browser's console. You should get "3.6.0" returned as your current jQuery version.

References