The AUI 8.0 release aims to achieve a few key things:
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.
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 8.0 changes how the library is composed and distributed.
Explicit dependencies on the pieces of AUI that are actually needed is encouraged over inheriting components or behaviours as a side-effect.
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.
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.
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.
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.
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:
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.
| Change | Alternative |
|---|---|
AJS() has been removed. |
Use jQuery or native browser APIs to create DOM elements. For example:
|
window.AJS is now an object, not a function. |
In previous versions of AUI:
In AUI 8, passing Review your usage of |
AJS.toInit(<Function>) will always run the function asynchronously. |
The order in which your initialisation functions will run may change, which may invalidate implicit assumptions in your code. Review your usage of all patterns of handling "document ready". Pick one code pattern.
If you need to ensure your initialisations occur in a specific order, we recommend
sharing a reference to a |
The following functions have been removed from AUI's browser module:
|
AUI 8's supported browsers (IE 11 and higher) support these behaviours natively, so feature detection should not be necessary. |
The following jQuery plugins have been removed from AUI:
|
Projects that depend on these jQuery plugins should bundle them independently. |
AJS.bindEvt, AJS.triggerEvt, and AJS.triggerEvtForInst have been removed. |
No alternative will be provided. |
AJS.contains has been removed. |
No alternative will be provided.
Use Array.prototype.indexOf instead.
If your project does not support IE11, you can use Array.prototype.includes instead.
|
AJS.firebug and AJS.warnAboutFirebug have been removed. |
No alternative will be provided. |
AJS.filterBySearch has been removed. |
No alternative will be provided. If products require this function, this should be copied. |
AJS.include has been removed |
Use a proper module loader instead. |
AJS.indexOf has been removed. |
No alternative will be provided. Use Array.prototype.indexOf instead. |
AJS.isVisible has been removed. |
No alternative will be provided. |
AJS.message.template has been removed. |
No alternative will be provided. |
AJS.onTextResize and AJS.unbindTextResize have been removed |
No alternative will be provided. |
AJS.preventDefault and AJS.stopEvent have been removed. |
No alternative will be provided. |
AJS.setCurrent and AJS.setVisible have been removed. |
No alternative will be provided. Use jQuery.addClass() / removeClass() instead. |
AJS.toggleClassName has been removed |
Use another approach to adding/removing a class — for example, jQuery. |
| Removed class | Alternative |
|---|---|
| .success | .aui-message-success |
| .hint | .aui-message-hint |
| .warning | .aui-message-warning |
| .info | .aui-message-info |
| .error | .aui-message-error |
.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-warningUse iconfont icons as a replacement
.icon-dropdown.icon-dropdown-active.icon-dropdown-active-d.icon-maximize.icon-maximize-d.icon-minimize.icon-minimize-d.icon-move.icon-move-dUse iconfont icons as a replacement.
We removed .aui-icon-wait class and icon. You should replace it with spinner.
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.
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.
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.
| Old API | New API |
|---|---|
|
|
|
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.
| Old API | New API |
|---|---|
|
|
|
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.
| Old usage | New usage |
|---|---|
|
|
|
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 AUI 8.1, the team will release other pre-built bundles, then will explore making custom builds of AUI possible.
| Removed bundle file | Alternative bundle file | Recommended upgrade option |
|---|---|---|
|
The "core" AUI components
|
|
The "prototyping" bundle of AUI is not intended to be used in production systems. Add a comment to AUI-4829 noting the components and patterns you use. This will inform future efforts to build better bundles that contain only what you need. |
|
The "experimental" AUI components
|
|
The "prototyping" bundle of AUI is not intended to be used in production systems. Add a comment to AUI-4829 noting the components and patterns you use. This will inform future efforts to build better bundles that contain only what you need. |
Your product will need to:
| What | Why | |
|---|---|---|
| 1 | Bundle atlassian-plugins-webresource-plugin version 3.6.0 or higher in your project. | To make WRM.require and other WRM functions work. |
| 2 |
Add the following web-resource dependencies to your product superbatch or sync-batch:
|
To make translations work. |
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.
| Changed web-resource | Notes |
|---|---|
com.atlassian.auiplugin:ajs |
AUI's primary web-resource has been re-created and ships far less code. The following web-resources are no longer provided through this web-resource and must be depended upon explicitly:
The following web-resources are still provided through this web-resource, but they should be depended upon explicitly:
|
com.atlassian.auiplugin:aui-core |
AUI's "core" has been reduced in size and scope. In particular, it has been stripped of several deprecated utility functions. See the JS changes section for more details. |
com.atlassian.auiplugin:icons |
AUI's icon pattern has been split from the iconography definitions. If you only want the icon markup pattern, you can include just "aui-icon".
|
What follows is a list of web-resource keys that are either completely removed from AUI, or will have no alternative going forward.
| Removed web-resource | Alternative web-resource(s) | Notes |
|---|---|---|
com.atlassian.auiplugin:ajs-html5shim |
- |
This polyfill was no longer needed. |
com.atlassian.auiplugin:ajs-zepto |
- |
Import Zepto through your own project, or depend upon jQuery. |
com.atlassian.auiplugin:aui-css |
- |
Add dependencies on the specific components and patterns that are needed to render your UI. |
com.atlassian.auiplugin:aui-experimental-autocomplete-helpers |
- |
|
com.atlassian.auiplugin:aui-experimental-example |
- |
The "experimental" concept has been removed. Also, what was this an "example" of, exactly? Nobody knows! |
com.atlassian.auiplugin:aui-experimental-header-rotp |
com.atlassian.auiplugin:aui-header |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-mobile |
|
Compose the explicit set of web-resource keys you need. |
com.atlassian.auiplugin:aui-experimental-page |
|
Compose the explicit set of web-resource keys you need. |
com.atlassian.auiplugin:aui-experimental-module |
- |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-module-and-header-legacy1 |
- |
The "experimental" concept has been removed. Code marked as "deprecated" and "legacy" should not exist forever. |
com.atlassian.auiplugin:aui-experimental-page-layout-legacy1 |
- |
The "experimental" concept has been removed. Code marked as "deprecated" and "legacy" should not exist forever. |
com.atlassian.auiplugin:aui-experimental-page-layout-typography |
- |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-page-layout-typography-legacy1 |
- |
The "experimental" concept has been removed. Code marked as "deprecated" and "legacy" should not exist forever. |
com.atlassian.auiplugin:aui-experimental-progress-buttons |
com.atlassian.auiplugin:aui-button |
The "experimental" concept has been removed. This particular web-resource existed to put a spinner in the button, which is part of the button's core behaviour. |
com.atlassian.auiplugin:aui-experimental-soy-templates-legacy1 |
com.atlassian.auiplugin:soy |
The "experimental" concept has been removed. Code marked as "deprecated" and "legacy" should not exist forever. Also, how many soy resources that do exactly the same thing do you really need? |
com.atlassian.auiplugin:aui-mobile-suite |
|
Compose the explicit set of web-resource keys you need. |
com.atlassian.auiplugin:aui-tipsy |
- |
Tipsy was an implementation detail that will change. Use AUI's tooltip component directly. |
com.atlassian.auiplugin:binders |
- |
This behaviour existed only to provide unneeded browser polyfills, so was no longer needed itself. |
com.atlassian.auiplugin:deprecated-legacy-images |
- |
Code marked as "deprecated" and "legacy" should not exist forever. |
com.atlassian.auiplugin:hotkeys |
- |
This plugin is an internal implementation detail of AUI's keyboard shortcuts behaviour. |
com.atlassian.auiplugin:internal-aui-animation |
- |
|
com.atlassian.auiplugin:internal-aui-browser |
- |
|
com.atlassian.auiplugin:internal-aui-is-input |
- |
|
com.atlassian.auiplugin:internal-aui-widget |
- |
|
com.atlassian.auiplugin:internal-inline-dialog-common |
- |
|
com.atlassian.auiplugin:jquery-autocomplete-deprecated |
- |
Add the jQuery autocomplete plugin to your project. Look, even the key of this one told you not to use it. |
com.atlassian.auiplugin:jquery-ui-widgets |
- |
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 project. |
com.atlassian.auiplugin:jquery-effects |
- |
- |
com.atlassian.auiplugin:jquery-all |
com.atlassian.plugins.jquery:jquery |
AUI does not provide jQuery itself. AUI depends upon jQuery through a jQuery Atlassian plugin which a host product must provide. |
com.atlassian.auiplugin:jquery-aop |
- |
Add the jQuery.aop plugin to your project. |
com.atlassian.auiplugin:jquery-progressbar |
- |
Add the jQuery progressbar plugin to your project. |
com.atlassian.auiplugin:jquery-selection |
- |
Add the jQuery selection plugin to your project. |
com.atlassian.auiplugin:jquery-throbber |
- |
Add the jQuery throbber plugin to your project. |
com.atlassian.auiplugin:placeholder |
- |
This browser polyfill is no longer required. |
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.
| Deprecated web-resource | Alternative web-resource(s) | Notes |
|---|---|---|
com.atlassian.auiplugin:aui-page-suite
|
This web-resource was bundling several others. Depend upon the web-resources you need directly:
|
|
com.atlassian.auiplugin:jquery-form |
- |
You should include the jQuery form plugin in your own project code. |
com.atlassian.auiplugin:jquery-spin |
com.atlassian.auiplugin:aui-spinner |
Using <aui-spinner/> through jQuery is deprecated. Create a spinner element directly. |
com.atlassian.auiplugin:jquery-ui
|
This web-resource was bundling several others. Depend upon the web-resources you need directly:
|
jQuery UI is a combination of several behavioural utilities, interface components, and effects. This web-resource has a significant impact on page weight, since the whole of jQuery UI is quite large. |
com.atlassian.auiplugin:internal-jquery-ui-partial
|
This web-resource was bundling several others. Depend upon the web-resources you need directly:
|
|
com.atlassian.auiplugin:jquery-ui-interactions
|
This web-resource was bundling several others. Depend upon the web-resources you need directly:
|
|
com.atlassian.auiplugin:jquery-ui-other
|
This web-resource was bundling several others. Depend upon the web-resources you need directly:
|
|
com.atlassian.auiplugin:ajs-gadgets
|
This web-resource was bundling several others. Depend upon the web-resources you need directly:
|
|
com.atlassian.auiplugin:ajs-gadgets-base
|
This web-resource was bundling several others. Depend upon the web-resources you need directly:
|
This web-resource was bundling resources from |
|
|
com.atlassian.auiplugin:aui-iconography |
The "experimental" concept has been removed. The fact that icons are delivered through an iconfont is an implementation detail, thus did not make sense to enshrine in the key. |
com.atlassian.auiplugin:aui-experimental-soy-templates |
com.atlassian.auiplugin:soy |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-soy-templates-2 |
com.atlassian.auiplugin:soy |
The "experimental" concept has been removed. Also, we already *had* a web-resource key for these. I guess we just liked the number 2? |
com.atlassian.auiplugin:aui-experimental-avatars |
com.atlassian.auiplugin:aui-avatar |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-badge |
com.atlassian.auiplugin:aui-badge |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-buttons |
com.atlassian.auiplugin:aui-button |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-data-handlers |
com.atlassian.auiplugin:aui-progressive-data-set |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-date-picker |
com.atlassian.auiplugin:aui-date-picker |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-dropdown2 |
com.atlassian.auiplugin:aui-dropdown2 |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-expander |
com.atlassian.auiplugin:aui-expander |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-header |
com.atlassian.auiplugin:aui-header |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-labels |
com.atlassian.auiplugin:aui-labels |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-lozenge |
com.atlassian.auiplugin:aui-lozenge |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-navigation |
com.atlassian.auiplugin:aui-navigation |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-page-header |
com.atlassian.auiplugin:aui-page-header |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-page-layout |
com.atlassian.auiplugin:aui-page-layout |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-progress-indicator |
com.atlassian.auiplugin:aui-progress-indicator |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-progress-tracker |
com.atlassian.auiplugin:aui-progress-tracker |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-reset |
com.atlassian.auiplugin:aui-reset |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-restfultable |
com.atlassian.auiplugin:aui-restfultable |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-spinner |
Also include |
The "experimental" concept has been removed. The preferred method of creating spinners is with the web component. |
com.atlassian.auiplugin:aui-experimental-table-sortable |
com.atlassian.auiplugin:aui-table-sortable |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-toolbar2 |
com.atlassian.auiplugin:aui-toolbar2 |
The "experimental" concept has been removed. |
com.atlassian.auiplugin:aui-experimental-tooltips |
com.atlassian.auiplugin:aui-tooltip |
The "experimental" concept has been removed. |
| Symptom | What to do |
|---|---|
$.widget is undefined |
In the Node package:
In the Atlassian plugin:
|
|
|
Add the jQuery.aop plugin to your project. |
|
|
Add the jQuery form plugin to your project. In the Atlassian plugin:
|
$(...).draggable is not a function |
Add a dependency on jquery-ui/ui/widgets/draggable. In the Atlassian plugin:
|
$(...).droppable is not a function |
Add a dependency on jquery-ui/ui/widgets/droppable. In the Atlassian plugin:
|
$(...).mouse is not a function |
Add a dependency on jquery-ui/ui/widgets/mouse. In the Atlassian plugin:
|
$(...).position is not a function |
Add a dependency on jquery-ui/ui/position. In the Atlassian plugin:
|
$(...).resizable is not a function |
Add a dependency on jquery-ui/ui/widgets/resizable and jquery-ui/themes/base/resizable.css. In the Atlassian plugin:
|
$(...).selectable is not a function |
Add a dependency on jquery-ui/ui/widgets/selectable and jquery-ui/themes/base/selectable.css. In the Atlassian plugin:
|
$(...).sortable is not a function |
Add a dependency on jquery-ui/ui/widgets/sortable and jquery-ui/themes/base/sortable.css. In the Atlassian plugin:
|
|
|
The jQuery spin behaviour was split in to its own module, separate to the AUI spinner component. You should replace usage of these jQuery functions with spinner. In the Atlassian plugin:
|
|
|
Dropdown 1 was removed from AUI 8. Consult the removed components section for more details. |
|
|
Dialog 1 was removed from AUI 8. Consult the removed components section for more details. |
|
|
Inline Dialog 1 was removed from AUI 8. Consult the removed components section for more details. |
|
Cannot read property "fill" of undefined |
You need to explicitly import this function now. In the Node package:
In the Atlassian plugin:
|
|
Cannot read property "extend" of undefined Cannot read property "Model" of undefined |
Import your own version of Backbone.
In the Atlassian plugin for AUI 8, you can still import |
|
Cannot read property "filter" of undefined Cannot read property "map" of undefined Cannot read property "extend" of undefined |
Import your own version of Underscore.
In the Atlassian plugin for AUI 8, you can still import |
|
|
You need to explicitly import the keyboard shortcuts web-resource dependency:
|
|
The blue bar for the top menu is gone! The application header looks weird! |
You need to explicitly import the AUI application header component now. In the Atlassian plugin:
|
| Restful tables don't render any more! |
You need to explicitly import them now. In the Atlassian plugin:
|