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 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 insystemMessages
is an object literal that specifies data relevant to the notification event (seesystemMessages
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'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