AUI 9 upgrade guides
Upgrading from 8.x to 9.0
It will be focused as the first thing after dialog being opened unless
you set explicitly the
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)
Inline Dialog 2
Inline dialog element is now focused after opening.
Make sure you set
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 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.
In order to specify a rendering DOM container, set the
to a selector matching the container element:
data-aui-dom-containerattribute is set but the selector matches multiple elements - it will default to first available match.
data-aui-dom-containerattribute is set but the selector does not match to any existing elements it will default to
data-aui-dom-containerattribute 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.
ARIA attribute 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.
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:
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.
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-hiddenand replaced some of them with
- For several elements, we now use the
openattribute to indicate whether the element should be visible or not.
- AUI's CSS reset sets
display:none !importanton any element with the hidden attribute.
If your code tests for the visibility of an element, check for the presence of the
attribute and the absence of a
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
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.
Previously in our docs examples markup for Dialog2 included
aria-hidden="true" attribute on
Now you should add
|Old markup||New markup|
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|
Refactoring aria-hidden attributes required also changes in Layer component.
|Old behaviour||New behaviour|
AUI library changes
Sidebar expand button
We replaced custom icon with icon font. Make sure that the span now has
|Old markup||New markup|
"Message" close icon was removed. Following classes are no longer supported:
- .aui-message .icon-close
- .aui-message .icon-close-inverted
- .aui-message.error .icon-close
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/
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