Namespace: cq-message-toaster

stxx.dispatch("notification", { message: "A toast!" });

<cq-message-toaster
    defaultDisplayTime="10"
    defaultTransition="slide"
    defaultPosition="top"
</cq-message-toaster>

Methods

---

createMessageElement(notification)

Creates a new toast DOM element. Toast elements have the cq-toast-message class attribute.

Parameters:

Name	Type	Description
notification	object	Data object from a "notification" event. See notificationEventListener. Note: This parameter does not accommodate the string type specified in notificationEventListener. Properties Name Type Argument Default Description message string Text to display in the toast notification. Strings longer than 160 characters are truncated. position string <optional> "top" Position of the toast on the chart: "top" or "bottom". Overrides the defaultPosition attribute of the <cq-message-toaster> element. type string <optional> "info" Toast style: "info", "error", "warning", or "confirmation". Overrides the defaultTransition attribute of the <cq-message-toaster> element. transition string <optional> Type of animation used to display and dismiss the toast: "fade", "slide", "pop" or "drop". The default is no transition. displayTime number <optional> 10 Number of seconds to display the toast before automatically dismissing it. A value of 0 causes the toast to remain on screen — preventing other toasts from displaying — until the toast is selected by the user. Overrides the defaultDisplayTime attribute of the <cq-message-toaster> element. priority number <optional> 0 Priority of the toast relative to others in the display queue. Higher priority toasts are displayed before toasts with lower priority. For example, a toast with priority = 4 is displayed before a toast with priority = 1. Toasts with the same priority are displayed in the order they were created; that is, in the order they entered the display queue. callback function <optional> Function to call when the toast is selected (dismissed) by the user. If the toast is dismissed automatically (see displayTime), this function is not called.

Since:

• 8.2.0

Returns:

A toast DOM element.

Type

HTMLElement

---

dismissMessage(message)

Dismisses a message by removing it from the queue (including if it is already displayed).

Parameters:

Name	Type	Description
message	string	The message to dismiss.

Since:

• 8.4.0

---

displayNextMessage()

Displays the next toast in the display queue and sets a timer based on the toast displayTime property to automatically dismiss the toast.

Since:

• 8.2.0

---

handleResize()

Updates the position settings of all toasts (all DOM elements with class cq-toast-message), including those not currently displayed, when the chart is resized.

Since:

• 8.2.0

---

newMessage(notification)

Creates a new toast and adds it to a queue that determines the display sequence of concurrent toasts.

This function is the "notification" event listener. See notificationEventListener.

Parameters:

Name	Type	Description
notification	object | string	Either an object containing data relevant to the notification event or a string that identifies a property of the systemMessages property of the chart configuration object. The property contained in systemMessages is an object literal that specifies data relevant to the notification event (see systemMessages in the Chart Configuration tutorial). Properties Name Type Argument Default Description message string Text to display in the toast notification. Strings longer than 160 characters are truncated. position string <optional> "top" Position of the toast on the chart: "top" or "bottom". Overrides the defaultPosition attribute of the <cq-message-toaster> element. type string <optional> "info" Toast style: "info", "error", "warning", or "confirmation". Overrides the defaultTransition attribute of the <cq-message-toaster> element. transition string <optional> Type of animation used to display and dismiss the toast: "fade", "slide", "pop" or "drop". The default is no transition. displayTime number <optional> 10 Number of seconds to display the toast before automatically dismissing it. A value of 0 causes the toast to remain on screen — preventing other toasts from displaying — until the toast is selected by the user. Overrides the defaultDisplayTime attribute of the <cq-message-toaster> element. priority number <optional> 0 Priority of the toast relative to others in the display queue. Higher priority toasts are displayed before toasts with lower priority. For example, a toast with priority = 4 is displayed before a toast with priority = 1. Toasts with the same priority are displayed in the order they were created; that is, in the order they entered the display queue. callback function <optional> Function to call when the toast is selected (dismissed) by the user. If the toast is dismissed automatically (see displayTime), this function is not called.

Since:

• 8.2.0
• 8.4.0 Calling this method with a message that is already displayed or in the queue will return without doing anything.

---

positionElement(messageElement)

Sets the display position of the toast identified by messageElement within the bounds of the chart canvas. Centers the toast horizontally and positions it vertically based on the toast's position setting.

Parameters:

Name	Type	Description
messageElement	HTMLElement	The toast DOM element to position.

Since:

• 8.2.0

---

recallMessageNode(messageNode)

Removes the toast specified by messageNode from the DOM but not from the display queue.

Use this function to interrupt a toast and display one of higher priority. The interrupted toast is re-displayed by the next call to displayNextMessage.

Parameters:

Name	Type	Description
messageNode		The toast to recall.

Since:

• 8.2.0

---

removeMessageNode(messageNode)

Removes the toast specified by messageNode from the display queue and displays the next message in the queue.

Parameters:

Name	Type	Description
messageNode		The toast to remove from the display queue.

Since:

• 8.2.0