Messages

Ask a question Design guidelines

Summary

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 since:	3.0

Examples

Inserted with HTML

Backup stale

This instance was last backed up on Thursday, 18 September 2011.

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

Success!

You have backed up your system!

Custom Context Demo

Because you often need to specify where the message goes.

Code

There are several message types with different colours and icons. There are two ways to implement messages: using HTML (or Soy to generate the HTML) or using JavaScript.

HTML

Error!

And this is just content in a Default message.

HTML - deprecated markup

Error!

And this is just content in a Default message.

JavaScript

Note you should use the JS API if adding Messages with JavaScript, not the compiled-JavaScript-Soy API. Although the two seems similar, the JS API is the supported option.

Default context:

Note if you do not set the context, the element:

...must exist in your document, otherwise the message will not appear as it has no target location.

It is more common to set the context:

Methods

Method	Description	Example Usage
`makeCloseable`	Deprecated Adds the closeable class and cross icon to a message. This method is deprecated, use the supported constructor option 'closeable' instead.

Soy

Some details about the error so the user knows what to do.

Options

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()`

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.
`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.

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.