AUI 9 upgrade guides

Ask a question

Upgrading from 8.x to 9.0

Accessibility changes

Dialog2

Focus management

The dialog element itself is now focusable by JavaScript. It will be focused as the first thing after dialog being opened unless you set explicitly the data-aui-focus-selector attribute.

Close button

Make sure the close button:

  • is a button (and has a type="button" just in case you put it within HTML form somehow)
  • has an aria-label attribute, with a translation string that evaluates to "Close"
  • is in tab order (it will be by default if it's a button)

Markup example:

Inline Dialog 2

Inline dialog element is now focused after opening.

Make sure you set aria-label on aui-inline-dialog element to give screen reader friendly description of the the dialog's content. When aria-label is missing the AT will read whole content of the dialog.

Layered elements

Layered elements except Dialog2 are no longer appended to the body.

Layered elements except Dialog2 will not alter their allocation in DOM tree by default.
To maintain a natural tab order for keyboard users, layered elements should be rendered as the next sibling of their trigger.

It may happen that due to the design of your application the layered components may get obscured - i.e. being clipped by the parent container with overflow:hidden; CSS property set.

You may need to alter your application's CSS to adjust to the new behaviour.

In rare cases when such adjustments are not possible - you may specify a rendering DOM container for any layered component.
Upon displaying of such layered component - it will temporarily move it's subtree into the specified container - allowing for unobstructed rendering.
You should always choose the closest container allowing for unobstructed render.
You are responsible for ensuring the component is properly cleaned up, adequately to your application's lifecycle.

A11y warning

Specifying designated rendering DOM container may impact tab flow, information flow, focus or keyboard navigation patterns of the component.

It may result in your application being inaccessible for users dependant on keyboard navigation, controller navigation and/or using NVDA, VoiceOver or other assistive technologies.

In order to specify a rendering DOM container, set the data-aui-dom-container attribute to a selector matching the container element:

  • If data-aui-dom-container attribute is set but the selector matches multiple elements - it will default to first available match.
  • If data-aui-dom-container attribute is set but the selector does not match to any existing elements it will default to document.body
  • If data-aui-dom-container attribute is not set, the dropdown will be left in place.

Even though this API is available for all layered components, only the components that guarantee adequate tab, keyboard and/or focus flow management will expose this API in their documentation.
Always refer to the component's documentation to see if it exposes any means to overcome similar rendering obstacles, i.e. by setting proper alignment.

Dropdown2

Styling changes

Previously, specific ARIA attributes would receive styling when used in a dropdown container. Now, ARIA attributes receive no explicit styling.

If you are using the markup-based pattern (not the web-component pattern) for your dropdowns, You must use one the following patterns to receive the dropdown item aesthetic:

  • Use an <a> HTML element if the dropdown item will take the user to another page.
  • Use a <button> HTML element if the dropdown item will do something dynamic.
  • Use the .aui-dropdown2-radio or .aui-dropdown2-checkbox CSS classes to make an item present as a radio or checkbox respectively.

Note that these are changes to the CSS and affect visual aesthetic. You are responsible for using valid, semantic markup so that the items are perceived correctly in non-visual contexts, such as screen readers.

Application header

Markup changes

Previously, the application header's logo was wrapped in a <h1> element. The <h1> element should only be used inside the page's main content. The logo element has now been replaced with a <span> element.

The pattern's <nav> element must have an aria-label with a translated value of "site". This allows screen reader users to perceive the application header as "site navigation".

Make sure that the logo link has translation string that interpolates to "Go to home page" label.

Old markup New markup

Page layout changes

The .aui-panel class is gone

AUI used to include an .aui-panel CSS class. Its purpose was wholly replaced by .aui-page-panel in AUI 5. The upgrade is a simple 1:1 mapping: find and replace all .aui-panel with .aui-page-panel.

Page structure changes

The page layout pattern was updated; some markup changes were made to allow easier placement of key landmark roles, as well as to provide recommended labeling for each. Of note in the changes are:

  • Where to place the <main> element on your page.
  • The position of the sidebar has changed in markup.
  • The recommended tag names of interstitial markup between page structure and content are slightly updated.
  • Removal of redundant role attributes where all supported browsers and screen readers understand the native semantic of recommended tags.

Here are how some typical page layouts have changed in markup:

Changes to overall page structure
Changes to page content patterns

Please read the full page layout documentation page for more details on these changes.

Soy template changes

Previously, the aui.page.pagePanelContent template output a <section> element and had no id value.

In AUI 9, this template now outputs a <main> element with a default id value of main. It will also output the appropriate role attribute.

The following table demonstrates the differences in call output.

Changes to hiding and showing elements

AUI used to use aria-hidden attribute to visually hide elements, which is an incorrect usage of this attribute.

To improve how elements are shown and hidden, we made the following changes:

  • We removed invalid uses of aria-hidden and replaced some of them with hidden.
  • For several elements, we now use the open attribute to indicate whether the element should be visible or not.
  • AUI's CSS reset sets display:none !important on any element with the hidden attribute.

If your code tests for the visibility of an element, check for the presence of the open attribute and the absence of a hidden attribute.

If an element should be hidden immediately, add the hidden attribute to it.

If you animate any elements when they appear or disappear, you should do this with the open attribute. The hidden attribute takes precedence over open and will take effect immediately; it will not be possible to animate visibility when this attribute is added to an element.

Dialog2

Previously in our docs examples markup for Dialog2 included aria-hidden="true" attribute on section element.

Now you should add hidden attribute.

Old markup New markup

Dropdown2

If you are still constructing dropdowns using markup instead of webcomponent you may need to update your HTML. If you are using Soy templates provided by AUI you are fine if not, make changes described below.

Old markup New markup

Layer component

Refactoring aria-hidden attributes required also changes in Layer component.

Old behaviour New behaviour
If .hide() was called on a layer element:
  • that did not have aria-hidden attribute -> add aria-hidden="false" attribute
  • that did have aria-hidden="false" attribute -> do nothing
  • that did have aria-hidden="true" attribute -> hide element
 If .hide() was called on a layer element:
  • that did not have hidden attribute -> hide element
  • that did have hidden attribute -> do nothing

AUI library changes

Markup changes

Sidebar expand button

We replaced custom icon with icon font. Make sure that the span now has aui-iconfont-chevron-double-left class.

Old markup New markup

CSS changes

"Message" close icon was removed. Following classes are no longer supported:
  • .aui-message .icon-close
  • .aui-icon-close
  • .aui-message .icon-close-inverted
  • .aui-message.error .icon-close
  • .aui-icon-close-inverted

jQuery configuration

jQuery ajaxSettings configuration was removed. Please specify it globaly for product or add it per request where needed. More information here https://api.jquery.com/jQuery.param/

Datepicker placeholders

In previous versions AUI relied on the dateFormat option from the jQuery UI datepicker widget. It was used as a placeholder for the input of type "date" if the "overrideBrowserDefault" option was set to "true".

Since the default format is represented by string "yy-mm-dd" it was confusing users because "yy" stands for the long year format (4-digits) - not the short, 2-digits year format.

We decided to break the dependency between the input placeholder and the format string by extending the configuration API and allowing the placeholder to be set explicitly. That requires you to review all the usages of the datepicker widget and set placeholders where they are needed to clarify understanding of given input purpose.

Our recommendation here is to not use placeholders and put the expected date format next to the input label - mostly for the accessibility reasons. Use placeholders only as a last resport. We suggest representing real values - not the format string: eg. 2020-01-29 instead of yyyy-mm-dd

Upgrading from 9.0.x to 9.1

AUI library changes

AUI's version of Popper.js - a third party library supporting AUI's layered components - has been bumped to v2.4.4, up from v1.14.5.

Markup changes

Due to changes introduced with Popper.js - shape of certain attributes might have changed for those components.
x-* have been replaced with data-popper-*
For details - visit Popper.js Migration guide

Old markup New markup

Even though these attributes have been used as internal API only and not explicitly guaranteed - for compatibility reasons - x-placement attribute is provided by AUI's layered components.
It's use is considered as DEPRECATED, meaning - the attribute will be removed with further versions of AUI. If your application depends on the provided data - please adapt to new, namespaced markup data-popper-*