Message Tool

Last Updated: Sep 9, 2022
documentation for the dotCMS Content Management System

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

Visual example of a toast message.

Message Types

The four types of messages are:

  • SUCCESS
  • INFO
  • WARNING
  • ERROR

The four message types behave identically, with the exception of displaying a different icon:

The four message types displayed together.

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]])
ArgTypeDescription
messagestringThe content of the toast message. (Required)
ttlintegerA number representing the duration of the message, in seconds. Defaults to 5 if only the message argument is specified.
usersarrayA 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:

Display of Message Sub-Action specifying ttl of 5 and severity of INFO.

On this page