Messages are the primary method for providing system feedback in the product user interface. Messages include notifications of various kinds: alerts, confirmations, notices, warnings, info and errors.
| API status: | general |
|---|---|
| Web resource key: |
com.atlassian.auiplugin:aui-message
|
| AMD Module key: | N/A |
| Experimental API: | 3 |
| General API: | 5 |
There are several message types with different colours and icons.
Backup stale
This instance was last backed up on
Backing up attachments
Attachments will not be backed up. This needs to be done manually.
Destructive operation!
Data import will wipe all existing content - make sure you backup first!
Success!
You have backed up your system to C:/backups/filename.xml.
Change!
System updated in the background
There are a few ways to implement messages: using HTML (or Soy to generate the HTML) or using JavaScript.
Messages can be added through AUI's JavaScript API in two main ways. The most common is to inject the element inside a "context" element:
If the context selector is omitted, the message is added to a static location: an element
with id="aui-message-bar".
Note that if you do not set the context, and the aui-message-bar element does not exist, the message will not appear as it has no target location.
When adding an HTML message, you must ensure root element (.aui-message) has the desired message class. Calling from Soy or JavaScript wraps this into one call, for convenience.
Note: icon class have been deprecated. The old message classes are also deprecated, now namespaced with aui-message-
| Message type | Message class | Soy call | JavaScript function |
|---|---|---|---|
| Info | aui-message-info
|
call aui.message.info
|
AJS.messages.info()
|
| Error | aui-message-error
|
call aui.message.error
|
AJS.messages.error()
|
| Warning | aui-message-warning
|
call aui.message.warning
|
AJS.messages.warning()
|
| Confirmation | aui-message-confirmation
|
call aui.message.confirmation
|
AJS.messages.confirmation()
|
| Change | aui-message-change
|
call aui.message.change
|
AJS.messages.change()
|
| Success Deprecated | aui-message-success
|
call aui.message.success
|
AJS.messages.success()
|
| Generic Deprecated | aui-message-generic
|
call aui.message.generic
|
AJS.messages.generic()
|
| Hint Deprecated | aui-message-hint
|
call aui.message.hint
|
AJS.messages.hint()
|
If the message is more than just informational or there are obvious follow-up things a user could do,
add a list of actions to the message body to allow the user to easily take their next step.
Actions should have the appearance of a link, but should use the appropriate HTML element for
the action — for example, use a <button> when the action is handled
by JavaScript or does something on the current page; use an <a> when the action
can take the user to another location in the system.
If you want to allow the user to dismiss the message
These options are set by adding classes to the root aui-message div.
| Class | Effect | Example |
|---|---|---|
closeable
|
Adds a Close icon to the message which closes and removes the message when clicked. | |
fadeout
|
Since 5.1. Makes the message fade away after five seconds. The fadeout will be cancelled if the user interacts with it (hover or focus). Note the fadeout option is best used via JavaScript and should not be used on critical errors and other information the user must be aware of. |
These options are set by adding params to the Soy call.
| Param | Effect | Default |
|---|---|---|
| content | Required. Content to display within the message. | n/a |
| titleContent | Title text of the message. | n/a |
| id | ID attribute | n/a |
| isCloseable | Boolean. Set to true, makes the Message closeable. | false |
These options are set in the options object when creating a Message with JavaScript:
| Option | Description | Possible values | Default |
|---|---|---|---|
| (context argument) | You can override the default context by passing it into the first argument of the messages function. This is the only option set as an argument. | A string in the form of an ID selector | #aui-message-bar |
body
|
The main content of the message. | HTML | none |
closeable
|
Adds a control allowing the user to close the message, removing it from the page. | boolean | true |
id
|
Gives your message an ID attribute, useful for selecting the message later. | ID string (no hash) | none |
insert
|
Sets the insert point to the start (prepend) or end (append) of the context element (Option added in AUI 4.2),
Since AUI 8.1.0 messages also support insertion before (before) and after (after) the context element.
|
prepend, append, before, after | append |
title
|
Sets the title text of the message. | Plain text | none |
fadeout
|
(since 5.1) Toggles the fade away on the message | boolean | false |
delay
|
(since 5.1) Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false) | number | 5000 |
duration
|
(since 5.1) Fadeout animation duration in milliseconds (ignored if fadeout==false) | number | 500 |
| Event | Description |
|---|---|
messageClose |
Deprecated When a message is closed, messageClose is fired before the message is removed from the DOM, including a reference to the DOM element being removed. |
aui-message-close |
When a message is closed, aui-message-close is fired AFTER the element is removed, a reference to the message being removed is included in the event data. |