Atlassian User Interface upgrade

Still need help?

The Atlassian Community is here for you.

Ask the community

Jira 8.0 will include Atlassian User Interface (AUI) 8.0. While doing the upgrade ourselves, we've created some best practices to make it easier for you to update your add-ons.

Upgrade guide

The upgrade guide is already available. For more information, see AUI 8.0 upgrade guide.

Changes

In addition to the upgrade guide, we've listed the most important changes that come with AUI 8.0. These are the best practices that we've gathered while upgrading AUI in Jira 8.0.

icon alignment

Until now, vertical-align was set to text-top, and is now text-bottom.

How do I fix this?

Despite this change, the icons are displaying correctly, so just make sure everything looks right. If you're overriding AUI's vertical-align, remove these overrides and use the default text-bottom.

.icon-wait

The .aui-icon-wait class and icon have been removed.

How do I fix this?
  1. Use <aui-spinner></aui-spinner> instead.

  2. Add this dependency to atlassian-plugin.xml under the appropriate web resource:

    <dependency>com.atlassian.auiplugin:aui-spinner</dependency>

Global underscore

Global underscore has been deprecated, and shouldn't be used.

How do I fix this?
  1. Import the following AMD module instead: require('underscore')

  2. Add this dependency to atlassian-plugin.xml under the appropriate web resource:
    • <dependency>jira.webresources:underscore-1.8.3</dependency>
Global backbone

Global backbone has been deprecated, and shouldn't be used.

How do I fix this?
  1. Check for the usage of “Backbone” in *.js files.

  2. Import the following AMD module: require('backbone')

  3. Add one of these dependencies to atlassian-plugin.xml under the appropriate web resource.

    • (preferred) <dependency>jira.webresources:backbone-1.3.3</dependency>

    • <dependency>jira.webresources:ajs-backbone-amd-shim</dependency>

app-header

AUI no longer provides the AUI application header component by default. If you want to use it, you’ll need to explicitly import it.

How do I fix this?
  1. Find any occurrences of AUI headers in your add-ons.

    • In soy: call aui.page.header

    • In css: class aui-header

    • In html: nav.aui-header

  2. Add the following dependencies, as needed:

    • com.atlassian.auiadd-on:aui-header (old one: aui-header-async)

    • com.atlassian.auiadd-on:aui-header-unresponsive (static header)

jquery-ui

You’ll need to explicitly import the jQuery UI component.

How do I fix this?

Basic jQuery UI

Jira still provides basic jQuery UI via AUI. If that's enough for you, you can use it by adding the following dependency:

<dependency>jira.webresources:jquery-ui</dependency>

More features

If you need more features of the jQuery UI in your add-on, find the following web-resource keys, and add the relevant dependencies.

Web resource keyDependency to add

$(selector).draggable(...)

jira.webresources:jquery-ui-draggable

$(selector).droppable(...)

jira.webresources:jquery-ui-droppable

$(selector).mouse(...)

jira.webresources:jquery-ui-mouse

$(selector).position( { ... } )

jira.webresources:jquery-ui-position

$(selector).resizable(...)

jira.webresources:jquery-ui-resizable

$(selector).selectable(...)

jira.webresources:jquery-ui-selectable

$(selector).sortable(...)

jira.webresources:jquery-ui-sortable

inline-dialog1

InlineDialog1 is obsolete and no longer shipped by default.

How do I fix this?

There are two ways in which you can fix this:

  • Use aui-inline-dialog2 instead.

  • Add this dependency to make your current code work: com.atlassian.auiplugin:inline-dialog.


dialog1

Dialog1 is obsolete and no longer shipped by default.

How do I fix this?

There are two ways in which you can fix this:

  • Use aui-dialog2 instead.

  • Add this dependency to make your current code work: com.atlassian.auiplugin:dialog

dropdown1

Dropdown1 is obsolete and no longer shipped by default.

How do I fix this?

There are two ways in which you can fix this.

  • Use aui-dropdown2 instead.

  • Add this dependency to make your current code work: com.atlassian.auiplugin:dropdown

AJS()

AJS is now an object, not a function. Because of that:

  • AJS doesn't support creating DOM elements anymore.
  • AJS can't be used as a proxy for the document object, for example when triggering or listening to events:
    • $(AJS).trigger
    • $(AJS).bind 
How do I fix this?
  1. Search for executions of AJS() as a function.

  2. Rewrite the code using one of the following:

    • Native DOM functions

    • jQuery

For example:

  • Change AJS("div") to document.createElement, or jQuery("<div></div>"), or any other templating solution.
  • Change AJS.$(AJS).trigger('abcd') to $(document).trigger('abcd')
  • Change AJS.$(AJS).bind('abcd') to $(document).on('abcd')
async

Many things in AUI 8 are async by default, following on the Promise/A+ and jQuery3-compatibility. Just make sure that AJS.toInit is implemented in the async way.

AJS.Cookie

AJS.Cookie has been deprecated.

How do I fix this?

The cookie-related code has been included in jslibs, so you can reuse that:

  • AMD module: atlassian/libs/cookie-1.0.0

  • XML dependency: com.atlassian.plugin.jslibs:cookie-1.0.0

Also, AJS.Cookie is stil bundled in AUI 8 as a deprecated web-resource:

  • XML dependency: com.atlassian.auiplugin:cookie

jQuery-add-ons

Several jQuery add-ons and jQuery widgets are no longer shipped with AUI. Expand the section below for the full list and alternatives you can use.

How do I fix this?
add-on/widgetAlternative

aop

This add-on has been removed, but it seems to be used only by toggle-block. If that’s not the case, hoist the <resource> and reuse it.

jQuery form add-on

Add this dependency:

jira.webresources:jquery

.fn.progressBar

Add this dependency:

jira.webresources:jquery-progressbar

.fn.throbber

Add this dependency:

jira.webresources:jquery-throbber

.fn.spin

.fn.stopSpin

  • Add this dependency: jira.webresources:jquery-spin

  • Or use <aui-spinner> instead

.fn.selection

.fn.selectionRange

.fn.wrapSelection

If your add-on is using it, add this dependency:

jira.webresources:jquery-selection

ajs-zepto

ajs-zepto has been removed from AUI. However, you’ll use it only if you have a mobile version of your add-on. 

How do I fix this?
  1. Search for Zepto in your add-on.

  2. Use one of the following solutions:

    • Import Zepto into the project

    • Use jQuery instead

aui-message-classes

The following AUI message classes have been removed, and now need the aui-message prefix: success, hint, warning, info, and error.

How do I fix this?

Search for the aui-message class in the source code (java, js, soy, jsp, vm).

  1. Check for extra classes, like success, hint, warning, info, and error.

  2. Add the aui-message prefix to each of these classes, for example:

    • infoaui-message-info

    • erroraui-message-error

CSS classes

Old "messages" and "gadgets" icons CSS classes have been removed. Expand the sections below for the full list.

Removed messages icons...
  • .aui-icon-success
  • .aui-icon-warning
  • .aui-icon-info
  • .aui-icon-error
  • .aui-icon-hint
  • .aui-icon-generic
  • .icon-generic
  • .icon-error
  • .icon-hint
  • .icon-info
  • .icon-success
  • .icon-warning

Alternative:

You can use iconfont as an alternative.

Removed gadgets icons...
  • .icon-dropdown
  • .icon-dropdown-active
  • .icon-dropdown-active-d
  • .icon-maximize
  • .icon-maximize-d
  • .icon-minimize
  • .icon-minimize-d
  • .icon-move
  • .icon-move-d

Alternative:

You can use iconfont as an alternative.

Other CSS classes...

These classes have been removed, and AUI 8 doesn't provide any alternatives:

  • .aui-dropdown-icon
  • .aui-box-shadow
  • .vertical-tabs-aui-legacystyle2011
  • .aui-nav-current
  • .aui-zebra
  • -hero and -marketing variants of header sizes
Last modified on Aug 13, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.