AUI 8 upgrade guides

Upgrading from 8.5 to 8.6

aui-toggle component is no longer triggering change event when property is changed programmatically.

Developers can manually trigger a change event if they really, really want to, and are willing to handle the potential infinite loop cases themselves.

Upgrading from 8.4 to 8.5

Form fields

A range of HTML markup patterns for form radio and checkbox fields were rendering incorrectly in AUI 8.4, caused by the approach taken to style them. When using a pure-CSS solution, some markup patterns would end up with invisible checkbox or radio glyphs. The problem was tracked as AUI-5053.

The compromise was to add an additional explicit element via JavaScript and style that in AUI 8.5. The <input> elements are visually hidden, and the new element is rendered to appear as a faux form field glyph. This has implications for automated testing frameworks.

Selenium attempts to emulate what a real user would be able to do, so Selenium doesn't interact with hidden elements. However, users are able to interact with these faux form fields correctly. Mouse and screen-reader users can click the <label> element, which will focus and affect the <input>. Keyboard users can still focus the <input> element and interact with it directly.

If you are using automated testing frameworks, you can adapt to the new form field styles in one of three ways:

• Update your tests to interact with the field’s <label> rather than the <input> element directly. Interacting with the label has the added benefit of testing that your forms are accessible to screen reader users, since it demonstrates the DOM has a link between the two.
• Use one of your testing tool's lower-level programmatic APIs to find the <input> element and click it. For example, the following Java code can be used to control Selenium:

  WebElement el = driver.findElement(By.id("visually-hidden-input"));
  
  // this doesn't work out...
  el.click();
  // throws in webdriver 2 with something like "cannot click because another element is in the way"
  // throws in webdriver 3 with "cannot scroll element in to view"
  
  // this sometimes works out...
  (new Actions(driver)).moveToElement(el).click().perform();
  // works in webdriver 3 on zero-opacity, negative z-index, and clip-hacked elements ...
  // fails in webdriver 3 if the element was clipped outside an overflow boundary.
  // fails in webdriver 2
  
  // this seemingly always works out...
  ((JavaScriptExecutor)driver).executeScript("arguments[0].click();", el);
  // works in webdriver 3
  // works in webdriver 2
          

• During tests, override AUI’s CSS rule for hiding <input> fields, so your testing tool's default behaviours will continue to work.

  form.aui:not(.aui-legacy-forms) .checkbox input[type=checkbox],
  form.aui:not(.aui-legacy-forms) .radio input[type=radio] {
      position: static;
      width: auto;
      height: auto;
      clip: unset;
  }
          

  (Note that changing styles may invalidate any visual regression screenshots you are taking!)

When following any of these approaches, it is recommended you wrap them in an abstraction — such as a "page object" — so that tests can describe what they're testing, and the abstraction can handle the how.

Upgrading from 8.3 to 8.4

AUI 8.4.0 updates the style of form fields

Form styles

The form fields styles are updated to match ADG3. The biggest change is in input's background and borders. We aimed for forms and form fields dimensions to stay the same.

We provide toggle for enabling legacy styles if you have a need for that. To enable legacy styles add .aui-legacy-forms class to form element.

Form field aesthetic changes

The following differences exist between the old and new form field aesthetic:

These changes effectively bring the aesthetic of dropdown items in line with the treatment given to items in AUI's vertical navigation pattern.

Form field notifications

AUI's form notifications — the pattern of placing an icon within the right margin of a form field and showing an inline dialog when focussing the field — are now displayed as plain text descriptions below the field. The icon is now redundant, so has been removed from form fields when notifications are shown.

We have deprecated data-aui-notification-field attributes in favour of using a plain HTML markup instead.

<form class="aui">

    <div class="field-group">

        <label for="demo-info-message">Input with an info notification</label>

        <input id="demo-info-message"

               class="text"

               type="text"

               data-aui-notification-field

               data-aui-notification-info="Choose a username at least 6 characters long." />

    </div>

</form>

<form class="aui">

    <div class="field-group">

        <label for="demo-info-message">Input with an info notification</label>

        <input id="demo-info-message" class="text" type="text" />

        <div class="description">

            <p>Choose a username at least 6 characters long.</p>

        </div>

    </div>

</form>

<form class="aui">

    <div class="field-group">

        <label for="demo-info-message">Input with multiple error notifications</label>

        <input id="demo-info-message"

               class="text"

               type="text"

               data-aui-notification-field

               data-aui-notification-error='["This field has a problem.","In fact, it has two problems."]' />

    </div>

</form>

<form class="aui">

    <div class="field-group">

        <label for="demo-info-message">Input with multiple error notifications</label>

        <input id="demo-info-message" class="text" type="text" />

        <div class="error">

            <ul>

                <li>This field has a problem.</li>

                <li>In fact, it has two problems.</li>

            </ul>

        </div>

    </div>

</form>

General upgrade advice

Things to be aware of:

• If you have any overrides for base form styles they may have stopped working as we changed styles during the update.
• We use :not(.aui-legacy-forms) for new styles and .aui-legacy-forms for legacy ones. This increases all specificity by one class.

Because of this you should either:

• Remove any CSS overrides you may have made to AUI’s forms markup pattern.
• Adjust your CSS overrides to handle both the :not(.aui-legacy-forms) and .aui-legacy-forms variants of the pattern.

When building for multiple products or multiple versions of a product you should remove your overrides, as ability to detect and address the correct version of the product is minimal.

Focus rings

As a part of forms refresh we added focus rings to focused elements.

Depending on your markup and CSS some of our focus rings can be clipped. Look for overflow: hidden, position: absolute and z-index in our code for possible source of problems. We provide a css toggle to turn new styles off. To do this add .aui-legacy-focus class to body element.

Upgrading from 8.2 to 8.3

AUI 8.3.0 updates the style of messages and lozenges

Messages design

The new style of messages is based on Section Messages from Atlaskit. This aims to bring ADGS closer to ADG3. Borders are removed and type of message is now reflected by it's background instead.

Lozenges design

Text and background colors of both standard and subtle lozenges were updated and aligned with ADG3. We've also aligned the names with Atlaskit introducing in progress and removed lozenges as a replacement for current and error.

Upgrading from 8.x to 8.2

This release is all about improving how layered elements work. Most of our layered elements — Dialog, Dropdown, Inline dialog, Feature discovery dialogs Select 2, and Single select — have been adjusted to improve where they render on the page and how they stack.

While there are no public API changes to these components, some of their implementation details have changed and may need your attention when upgrading to this version.

AUI layering behaviour

The previous layering and alignment behaviours were provided by Tether.js. We have replaced this library with Popper.js.

Our layers were previously positioned synchronously upon the layered element being shown. With this update, layers are now positioned asynchronously in a requestAnimationFrame callback.

Our layered elements would previously receive CSS classes starting with aui-alignment-element-attached- and aui-alignment-target-attached-. These CSS classes were an implementation detail of Tether, and are no longer added.
CSS classes starting with aui-alignment-side- and aui-alignment-snap- are still available.

Upgrading from 7.9.x to 8.0

The AUI 8.0 release aims to achieve a few key things:

• Make it easier to consume only the pieces of AUI that you need.
• Re-evaluate what you get "by default" when importing AUI.
• Remove dead and deprecated code.
• Upgrade external library dependencies.

The release includes major backwards-incompatible changes to AUI.

All distributions of AUI are affected by this release. Some distributions have changed shape, others have been removed or rebuilt from the ground up.

Major changes

The "core" and "experimental" concepts were removed from AUI. These concepts referred to API stability and component maturity, but were enshrined in many parts of AUI — from its documentation through to its distribution bundle filenames.
Splitting AUI in this way often left consumers with little choice but to include all of AUI's bundles in their production application, since they could not specify what it was they actually needed.

AUI packaging

AUI 8.0 changes how the library is composed and distributed.

• The library will be de-composed in to multiple Node packages over time.
• Long-deprecated components will be delivered as separate Node packages and unbundled from the main AUI package.
• The "experimental" concept is gone from AUI. Instead, components under test will be delivered as separate Node packages.
• The "core" concept is gone from AUI. Instead, the various bundles of AUI — both in Node and in the Atlassian Plugin — will include fewer components by default.

AUI dependencies

Explicit dependencies on the pieces of AUI that are actually needed is encouraged over inheriting components or behaviours as a side-effect.

jQuery and jQuery UI

New minimum versions

• The minimum required version of jQuery is now 2.x, up from 1.7.2.
• The version of jQuery UI that AUI uses has been bumped to 1.12.1.

If you are upgrading from jQuery 1.7.x or 1.8.x, you will need to be aware of the changes and removals that jQuery made in 1.9.x and beyond. See the jQuery 1.9 upgrade guide for more details.

Several features of jQuery were removed and externalised in the jQuery migrate plugin. Some of these features have been "fixed" or otherwise had their behaviours changed after being externalised in jQuery migrate, such as jQuery.browser.
You will need to need to audit your usage of jQuery APIs that were removed before jQuery 2.x, pulling in jQuery migrate if necessary, and ensure that your code works with the new behaviours.

API status

AUI considers jQuery and jQuery UI to be a deprecated implementation detail of its components and are not considered part of AUI's public API.

jQuery UI is a combination of several behavioural utilities, interface components, and effects. Though useful, it is a painful set of code to pull in and depend upon, since it fundamentally relies upon mutating a shared global object and encourages implicit dependencies that are hard to trace.

In AUI 8.0, all of jQuery UI's interface components have been removed from AUI. Developers depending upon jQuery UI interface components should either use the equivalent AUI component, or import the specific jQuery UI components they need within their own application's dependency graph.

In AUI 8.0, several parts of jQuery UI may still be added to the window.jQuery object, though this is considered an unintentional side-effect. Future versions of AUI may remove all usage of jQuery UI.

Backbone and Underscore

New minimum versions

• Backbone has been bumped to 1.3.3, up from 1.1.2.
• Underscore has been bumped to 1.9.1, up from 1.6.0.

Refer to the Backbone changelog for a list of behavioural and API changes in Backbone.

Refer to the Underscore changelog for a list of behavioural and API changes in Underscore.

API status

AUI considers Backbone and Underscore to be a deprecated implementation detail of its components and are not considered part of AUI's public API.

Backbone and Underscore are not added to window by AUI any more by default. If you depend on these libraries, you must pull in your own.

In Atlassian plugins, it is possible to add them to the window by explicitly requiring their web-resource keys, though this approach is deprecated and will be removed in AUI 9.0.

AUI components removed

Three of AUI's oldest components — Dialog 1, Dropdown 1, and Inline Dialog 1 — are no longer bundled with AUI from AUI 8 onwards. Each of these components has a more modern equivalent, which is where performance, accessibility, and usability improvement efforts are made.

There are upgrade guides for each component to migrate from the old component APIs to the new ones:

• Dialog 1 → Dialog 2
• Dropdown 1 → <aui-dropdown-menu>
• Inline Dialog 1 → <aui-inline-dialog>

For Node package consumers, these removed components will be made available through their own Node packages, independent of AUI.

For Atlassian plugin consumers, the components are still available through deprecated web-resource keys. These keys will be removed in AUI 9.0, at which time it will be the responsibility of consumers to have either migrated their usage of these components to their modern equivalents, or added the components to their products via the Node packages.

AUI library changes

JS changes

CSS changes

Un-prefixed AUI message classes have been removed

Old "messages" icons CSS classes have been removed

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

Use iconfont icons as a replacement

Old "gadget" icons CSS classes have been removed

• .icon-dropdown
• .icon-dropdown-active
• .icon-dropdown-active-d
• .icon-maximize
• .icon-maximize-d
• .icon-minimize
• .icon-minimize-d
• .icon-move
• .icon-move-d

Use iconfont icons as a replacement.

Icon Wait removed

We removed .aui-icon-wait class and icon. You should replace it with spinner.

Vertical alignment for icons changed

In AUI 8.0, we removed vertical-align: text-top from .aui-icon-small and .aui-icon-large. The alignment of some icons is wrong when text-top is used. Icons will be now using vertical-align: text-bottom which seems a more sensible default than text-top.

Check if your icons are aligned properly and remove possible unnecessary overrides.

Component changes

Restful table AJAX behaviours

Prior to AUI 8.0, when calling EntryModel#destroy, the AJAX request would use URL parameters to pass data to the server.

In AUI 8.0, the AJAX request now passes data in the request body. This makes the behaviour compatible with jQuery 2.x and jQuery 3.x.

Consumers are advised that any URL handling or logging on the server-side that expects to see parameters in the URL will no longer work, and will need to be updated to consume the request body instead.

Restful table delete confirmation

The docs were outdated and described deleteConfirmation option as boolean but the code was actually expecting callback function returning html which would be put inside Dialog1.

We removed dependency on Dialog1 and replaced deleteConfirmation option with deleteConfirmationCallback. Now we require you to provide a function returning promise. If promise is resolved row will be deleted, if rejected deletion will be prevented.

new AJS.RestfulTable({

    el: ...,

    deleteConfirmation: function(model) {

        return `<p>are you sure you want to delete ${model.id}?</p>`

    }

});

new AJS.RestfulTable({

    el: ...,

    deleteConfirmationCallback: function(model) {

        // The delete confirmation is always asynchronous now.

        // You can return any "then"-able object, such as

        // a native Promise, jQuery Deferred object, etc.

        return new Promise(function(resolve, reject) {

            // It is now up to you to choose how to ask the user for confirmation.

            var shouldRemove = confirm(`are you sure you want to delete ${model.id}?`);

            if (shouldRemove) {

                resolve();

            } else {

                reject();

            }

        });

    }

});

Tooltips

If you are upgrading past jQuery 1.9, your tooltips usage will require updating if they make use of Tipsy's live option. This is due to the internals of jQuery changing.

<ul id="old-tooltip-live-binding">

    <li><a title="The first link" href="#">First</a></li>

    <li><a title="The second link" href="#">Second</a></li>

    <li><a title="The third link" href="#">Third</a></li>

</ul>

AJS.$("#old-tooltip-live-binding a").tooltip({

    live: true

});

<ul id="new-tooltip-live-binding">

    <li><a title="The first link" href="#">First</a></li>

    <li><a title="The second link" href="#">Second</a></li>

    <li><a title="The third link" href="#">Third</a></li>

</ul>

AJS.$(document).tooltip({

    live: "#new-tooltip-live-binding a"

});

Dropdown2 Triggers

If you are using soy templates to render the Dropdown2 trigger, there is a chance you might have an extra icon in HTML that will render additional spacing.

{call aui.dropdown2.trigger}

    {param id: 'my-trigger' /}

    {param tagName: 'button'/}

    {param content}

        {call aui.icons.icon}

            {param useIconFont: true /}

            {param icon: 'more' /}

            {param accessibilityText: getText('bitbucket.web.branch.actions.menu.label') /}

        {/call}

    {/param}

    {param extraClasses: 'aui-button aui-button-subtle aui-button-compact' /}

    {param menu: [ 'id' : 'my-menu' ] /}

{/call}

{call aui.dropdown2.trigger}

    {param id: 'my-trigger' /}

    {param tagName: 'button'/}

    {param content: ''/}

    {param iconClasses: 'aui-icon-small aui-iconfont-more' /}

    {param iconText: getText('bitbucket.web.branch.actions.menu.label') /}

    {param extraClasses: 'aui-button aui-button-subtle aui-button-compact' /}

    {param menu: [ 'id' : 'my-menu' ] /}

{/call}

How to handle the upgrade

Node distribution migration

As mentioned in the packaging section, a number of changes were made to how AUI is distributed. These affect the Node distribution in a significant way.

In AUI 8.0, the Node package has been completely emptied of content. The resulting package is very small, but does not cover every use-case or usage scenario that the previous package may have covered incidentally.

The AUI team are collecting information about what the Node distribution should support in the AUI-4829 ticket. In future releases of AUI, the team will release other pre-built bundles, then will explore making custom builds of AUI possible.

Bundle changes

Atlassian plugin migration

Your product will need to:

A great many web-resource keys were removed from AUI, as the code they wrapped is no longer part of the library itself. Some web-resource key names were changed for internal consistency.

When upgrading, check the logs of your application as AUI is started. The WRM will list a number of deprecated web-resource keys and their alternatives.

web-resource changes

Removed web-resources

What follows is a list of web-resource keys that are either completely removed from AUI, or will have no alternative going forward.

Deprecated web-resources

The following list of web-resources are deprecated with reasonable alternatives.

In general, "bundle" web-resources are deprecated in favour of individual web-resource keys. Importing multiple smaller dependencies helps keep page weight low and helps make your app code dependencies easier to reason about.

Common runtime errors