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.
Status
API status:
general
Included in AUI core?
Yes. You do not need to explicitly require the web resource key.
Web resource key:
com.atlassian.auiplugin:message
AMD Module key:
N/A
Experimental API:
3
General API:
5
Examples
There are several message types with different colours and icons.
Inserted with HTML
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.
Inserted with JS
You successfully backed up your system! High-five!
Custom Context Demo
Because you often need to specify where the message goes.
It's dark in here... just the way Grues like it.
Code
There are a few ways to implement messages: using HTML (or Soy to generate the HTML) or using JavaScript.
body: '<p> And this is just content in a Default message.</p>'
});
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.
Soy
{call aui.message.warning}
{param title: 'An error occurred - user intervention required!' /}
{param closeable: 'true' /}
{param id: 'messageIDattribute' /}
{param content}
<p>Some details about the error so the user knows what to do.</p>
{/param}
{/call}
Types of messages
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
Generic Deprecated
aui-message-generic
call aui.message.generic
AJS.messages.generic()
Error
aui-message-error
call aui.message.error
AJS.messages.error()
Warning
aui-message-warning
call aui.message.warning
AJS.messages.warning()
Success
aui-message-success
call aui.message.success
AJS.messages.success()
Info
aui-message-info
call aui.message.info
AJS.messages.info()
Hint Deprecated
aui-message-hint
call aui.message.hint
AJS.messages.hint()
Message actions
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.
<p>It's dark in here... just the way Grues like it.</p>
<ulclass="aui-nav-actions-list">
<li><buttonclass="aui-button aui-button-link">Turn on the light</button></li>
<li><buttonclass="aui-button aui-button-link">Take your chances</button></li>
</ul>
</div>
Closeable
If you want to allow the user to dismiss the message
Options
HTML options
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.
<divclass="aui-message closeable">...</div>
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.
<divclass="aui-message fadeout">...</div>
Soy options
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
JavaScript options
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)
prepend, append
append
shadowed
Toggles the dropshadow on the message box. Usually not changed from default.
boolean
true
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
AJS.messages events
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.
$(document).on('aui-message-close', function (e) {