jQuery upgrade

Preparing for Jira 8.0

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Jira 8.0 will include jQuery 2.2.4. While doing the upgrade ourselves, we've created some best practices to make it easier for you to update your add-ons. Apart from the changes listed below, we’ve also attached some useful links to official jQuery upgrade guides, if you needed more information.

Good to know

Versions

We're upgrading jQuery from version 1.7.2 to 2.2.4. We'll also include the jQuery migrate plugin 1.4.1 to simplify the upgrade. The migrate plugin will allow you to use deprecated features so that your code still runs properly on the upgraded jQuery. However, you should treat it as a temporary solution, and migrate your code fully, as we’ll be removing the migrate plugin in the next releases.

Security issues

jQuery 2.2.4 shipped with Jira will get two additional security patches to address the following security issues: 

Change log and upgrade guide

We'd recommend that you have a look at the official jQuery change log and upgrade guide to get an idea of all the important changes and have some accurate information on hand if something is not clear.

Warnings about deprecated resources

After upgrading jQuery, the migrate plugin displays information messages and warnings whenever you use deprecated functions. These functions are still available and working, but since we’re planning to remove them in the future, it might be a good idea to change them to the supported ones. Warnings will help you identify where are you using them.

In the previous EAPs, warnings were enabled by default, but we’ve disabled them in the EAP Beta. If you want to display them again, enable the jquery-migrate-logging module.

  1. Go to  > Add-ons > Manage apps.
  2. Search for the jquery plugin.
  3. Enable the jquery-migrate-logging module.

Changes

The tables below show the most important changes. This is not an exhaustive list, and you should review it together with the jQuery upgrade guide. 

jQuery path changed in embedded issue collectors

The path to jQuery has changed in issue collectors. Specifically, in the code that allowed you to embed an issue collector outside of Jira. If you created one and embedded it by using the generated code, it will not work as the code is no longer accurate.

How do I fix this?

The path has been updated in the "new" generated code, so reuse it on all pages where you embedded your issue collectors.

  1. Open your issue collector. You can view all of them in > System > Issue collectors.
  2. Copy the updated code from the 'Embedding this issue collector' section.
  3. Use the code wherever you had the issue collector embedded.
Deferred.then

Before the upgrade, the then method was aligned to some degree with the Promise/A spec, and was used as syntactic sugar for attaching handlers on done and fail. Now, it behaves similarly to the Promise/A+ spec: it can change the value, and can be chained.

Docs: deferred.then(), enhancement request, commit history

How do I fix this?

You can use one of the following approaches:

  • Rewrite to native Promise.
  • Change then → done/fail methods.
  • Leave the code as-is, as some use cases may fit into the new behavior of then. You'll need to verify that, though.
isResolved, isRejected

This method has been replaced with deferred.state(), which returns one of the following states: pending, resolved, or rejected.

Docs: deferred.state(), deferred.isRejected(), deferred.isResolved()

How do I fix this?

Replace .is<State>() with .state() === "<state>", for example:

if (myPromise.isRejected()) → if (myPromise.state() === "rejected")
selector,comma
The jQuery selector can't end with a comma.
How do I fix this?

  • Remove trailing commas from selectors, for example: 

    $(".class-name, ") → $(".class-name")
.closest(selectors)

The signature of the .closest() method that uses Array has been removed. Normal uses of .closest() are not affected by this change.

Docs: closest(selectors), jQuery 1.8 blog

How do I fix this?

Rewrite the code so it's not using this signature. 

$.ajax{async:false}

Synchronous requests (SJAX) must use callbacks instead of Deferreds.

Docs: jQuery.ajax(), enhancement request, alternative method

How do I fix this?
  • In most cases, you should use AJAX instead of SJAX. 
  • Use success/error/complete callbacks instead of Deferred (e.g. .done()).
state@syntheticClick

Before the upgrade, an event triggered by a click on radio/checkbox elements would see these elements in the opposite state than that of a user action. This has been fixed to reflect the same checked state as a user-initiated action.

Docs: bugfix, jQuery 1.9 upgrade guide

How do I fix this?

Invert the logic that checks the new state for a programatically triggered click on radio/checkbox elements.

events@.fn.data

jQuery.fn.data() won't fire events (getData, setData, changeData) each time a data item is modified.

Docs: bugfix

How do I fix this?

Rewrite the code that uses the getData, setData, and changeData events.

namespace@.fn.data

jQuery.fn.data() won't support namespaced data.

Docs: bugfix, jQuery 1.9 upgrade guide

How do I fix this?
  • Rewrite the code that uses periods (.) as data keys.
  • As of jQuery 1.9, a call to .data("abc.def") retrieves the data for the name abc.def, and not just abc.
$.proxy

Preserve context when jQuery.proxy was called with a falsy context.

Docs: feature request, jQuery 1.9 upgrade guide

How do I fix this?

Rewrite the code.

$.contains

The first argument must be a DOM element, not a jQuery object.

Docs: jQuery.contains(), alternative method: Node.contains()

How do I fix this?
  • Use DOM elements, as described in the docs. This method no longer works with jQuery objects.
  • The difference between jQuery.contains() and the alternative Node.contains() is that the jQuery one is self-exclusive, i.e. it intentionally says an element does not contain itself. 
  • If you really need to use jQuery objects, you can use the following workaround, however it's not the best idea from the performance perspective:
    $(contained, container).length === 0 
$.uuid

This method has been removed.

Docs: jQuery 1.9 upgrade guide

How do I fix this?

Rewrite the code so it's not using this method.

$.offset.bodyOffset

This method has been removed.

Docs: alternative method: offset()

How do I fix this?

Rewrite the code so it's not using this method. You can use the .fn.offset method instead.

$.browser.version

A way to recognize the webkit browser version has changed. In the case of webkit, the previous version of $.browser.version returned the version of the browser engine. Now, it returns the correct browser version.

How do I fix this?
  • Check for browser.version occurrences, and rewrite the code.
  • Jira ships this implementation of jQuery.browser.
$.fn.width

A way to calculate the width of elements has changed. jQuery 2.2.4 returns different values for width (%) values on inline elements that have no content, so you should be extra careful when checking the width of these elements.

Docs: width()

How do I fix this?
  • Check the usage of width. In most cases, it should be enough to add display: inline-block on an inline element, or change width() with .css({width}).
$.focus()

The event handler won't be triggered if the elements on which you call .focus() are not attached to DOM.

How do I fix this?
  • Use triggerHandler('focus'), or attach the element to DOM.
Last modified on Aug 13, 2019

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.