The Message Tool ($messagetool) allows control of a class of small notification messages sometimes referred to as “toast messages,” or simply “toasts.”
dotCMS uses web sockets to send asynchronous messages to the client from the back end, usually displayed in a small box on the right side of the screen. These should not be confused with notifications, which are delivered via the bell icon in the upper-right corner.
Message Types
The four types of messages are:
SUCCESSINFOWARNINGERROR
The four message types behave identically, with the exception of displaying a different icon:
Usage
$messagetool has four methods, corresponding to the four message types, each of which accept the same arguments:
$messagetool.sendInfo(message[, ttl[, users]])
$messagetool.sendSuccess(message[, ttl[, users]])
$messagetool.sendWarning(message[, ttl[, users]])
$messagetool.sendError(message[, ttl[, users]])
| Arg | Type | Description |
|---|---|---|
message | string | The content of the toast message. (Required) |
ttl | integer | A number representing the duration of the message, in seconds. Defaults to 5 if only the message argument is specified. |
users | array | A velocity array containing the IDs of all users that should see the message, if restricted. ttl must be specified if users is passed to the function. |
As a simple example, the following code was used to generate the messages in the screenshot above:
$messagetool.sendInfo('This is a toast info message', 25)
$messagetool.sendSuccess('This is a toast success message', 25)
$messagetool.sendWarning('This is a toast warning message', 25)
$messagetool.sendError('This is a toast error message', 25)
$messagetool calls can be made directly from a VTL file, for example as a conditional notification:
#if ($someCondition)
$messagetool.sendError(‘Something went wrong’)
#end
They can also be called from the workflow pipeline In one of two ways:
- Use the Velocity Script Sub-Action to perform the
$messagetoolcalls - Use the Message Sub-Action to specify the parameters directly, setting the “Severity” to the message type:
SUCCESS,INFO,WARNING, orERROR.
