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'sposition
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