Library Documentation

Namespace: cq-message-toaster

WebComponents. cq-message-toaster

Message Toaster web component <cq-message-toaster>.

Displays pop-up messages, also known as toasts.

Listens for a chart engine event of type "notification" and displays the notification as a pop-up message over the chart.

To trigger the notification event, call CIQ.ChartEngine#dispatch with the "notification" type and the required notification listener data (see notificationEventListener), for example:

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

Toasts are displayed immediately unless another toast is already on screen. Concurrent toasts are displayed sequentially, not simultaneously.

When a toast is created, it's added to a display queue. The toast at the front of the queue is dequeued and displayed when no other toasts are on screen. Toasts can be prioritized (that is, reordered in the queue) by setting the priority parameter of the notificationEventListener argument.

Attributes:

Name Description Valid Values
defaultDisplayTime Amount of time, in seconds, toasts are displayed before being automatically dismissed (removed from the display). Integer numbers >= 0. A value of 0 causes toasts to remain on screen — blocking the toast display queue — until selected by the user.
defaultPosition Vertical on-screen position of toasts relative to the chart. (Toasts are centered horizontally.) "top" or "bottom"
defaultTransition Animation used to display and dismiss toasts. "fade", "slide", "pop" or "drop"

Note: All attributes can be overridden by the argument provided to notificationEventListener.

Since:

  • 8.2.0

Example

<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 from a "notification" event. See 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

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.

Parameters:
Name Type Description
notification object

Data from a "notification" event. See 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

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