API Reference
Namespaces
Classes
Events
Global
Externals

Class: MessageToaster

WebComponents. MessageToaster

This is a custom HtmlElement (Web Component). The tag name is the following:

<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
default-display-time 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.
default-position Vertical on-screen position of toasts relative to the chart. (Toasts are centered horizontally.) "top" or "bottom"
default-transition Animation used to display and dismiss toasts. "fade", "slide", "pop" or "drop"

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

Emitters

A custom event will be emitted by the component when a toast message is dismissed due to either:

  • click (user interaction)
  • alert (internal removal request)
  • timeout (expiration)

See CIQ.UI.BaseComponent#emitCustomEvent for details on how to listen for this event. The details of the event contain the following:

property value
emitter this component
cause "useraction", "alert", "timeout"
effect "remove"
action "click", null
displayTime time before automatically dismissing
message toast message
priority toast priority
type toast style

A custom event will be emitted by the component when a toast message is displayed, or removed from the message queue. See CIQ.UI.BaseComponent#emitCustomEvent for details on how to listen for this event. The details of the event contain the following:

property value
emitter this component
cause "alert"
effect "display", "recall"
action null
displayTime time before automatically dismissing
message toast message
priority toast priority
type toast style

<protected> new MessageToaster()

Since:
  • 8.2.0 Added
  • 9.1.0 Observes attributes. Added emitter.
Example
<cq-message-toaster
    default-display-time="10"
    default-transition="slide"
    default-position="top"
</cq-message-toaster>

Extends

Methods

addClaim()

Claim any keystrokes that come in. Once claimed, any keystrokes that come in are passed to the element. The element can then choose to capture or propagate the keystrokes. This enables an element to capture keystrokes even if it doesn't have mouse focus.

Inherited From:
Overrides:

addDefaultMarkup(component [, markup])

Adds default markup to a web component if the component does not have any child nodes.

Parameters:
Name Type Argument Description
component HTMLElement

The component to which the markup is added.
markup String <optional>

The markup to add to the web component. Unused if the component has a static markup property that specifies the markup; for example, MyComponent.markup.
Since:

  • 7.5.0

Inherited From:
Overrides:

channelMergeObject(path, value, stx)

Merges an object in the chart engine communication channel.

Parameters:
Name Type Description
path String

The channel path.
value Object

The value merged to the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:

channelRead(path [, stx])

Reads the current value in the chart engine communication channel.

Parameters:
Name Type Argument Description
path String

The channel path.
stx CIQ.ChartEngine <optional>

Unused.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The current value in channel.

Type
*

channelSubscribe(path, cb, stx)

Subscribes to the chart engine messaging channel.

Parameters:
Name Type Description
path *

The channel path.
cb *

A callback invoked upon subscribing and whenever a new message is posted in the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

A callback invoked when unsubscribing from the channel.

Type
function

channelWrite(path, value, stx)

Writes in the chart engine communication channel.

Parameters:
Name Type Description
path String

The channel path.
value *

The value written to the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:

clickFocusedItem(items, e)

Selects (clicks) the first element in items that has a cq-focused attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
e Event

The keystroke event.
Since:

  • 8.3.0

Inherited From:
Overrides:

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 default-position attribute of the <cq-message-toaster> element.
type string <optional>
 "info"

Toast style: "info", "error", "warning", or "confirmation". Overrides the default-transition 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 default-display-time 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

deactivateItem(item)

Blurs and removes the cq-keyboard-active attribute from item.

Parameters:
Name Type Description
item HTMLElement
Since:

  • 8.4.0

Inherited From:
Overrides:

disconnectedCallback()

Removes all the the injections for a context tag and resets the tag to its default state.

Designed to be used as a helper method for the included WebComponents. A full tutorial on how to work with and customize the WebComponents can be found here: Web Component Interface.

Inherited From:
Overrides:

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

emitCustomEvent(params)

Emits a custom event from the webcomponent. The event type of the emitted event is determined by the particular user action taken. Up to two events are emitted when this function is executed. The first is an event with the type of action performed, if there is one. For example, events which are spawned without user action will not emit this first event. The second event will have a type derived from the component name. For example, the cq-study-legend component will emit a "StudyLegend" type event. The payload of the event will contain a detail section specifying the component which emitted the event as well as the effect - which more clearly defines the type of action causing the emittance. The detail section may also include custom fields further categorizing the event and providing additional information. These details are documented within the web component's documentation.

Parameters:
Name Type Description
params object
Properties
Name Type Argument Default Description
cause string <optional>

The cause of the event. e.g., useraction, timeout, alert. Defaults to "useraction" if not set and action parameter is set.
effect string <optional>

The effect of the user's action. Required if not provided in detail. e.g., open, help, toggle, select.
action string | null <optional>
 "click"

The action a user performed, if applicable. e.g. click, longpress, drag. Set to null if no user action was performed.
detail Object <optional>
 {}

Optional extra parameters to include in the detail of the Custom Event.
Since:
  • 8.9.0
  • 9.1.0 Changed params object's property names.
Inherited From:
Overrides:

findFocused(items)

Finds the elements in items that have a cq-focused attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
Since:

  • 8.3.0

Inherited From:
Overrides:
Returns:

The elements in items that have a cq-focused attribute, or an empty array if no elements are found.

Type
array

findKeyboardActive(items)

Finds the elements in items that have a cq-keyboard-active attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation
Since:

  • 8.4.0

Inherited From:
Overrides:
Returns:

The elements in items that have a cq-keyboard-active attribute, or an empty array if no elements are found.

Type
Array

focusItem(item)

Adds a cq-focused attribute to item and highlights item.

Parameters:
Name Type Description
item HTMLElement

Element that receives keyboard focus and is highlighted.
Since:

  • 8.3.0

Inherited From:
Overrides:

focusNextItem(items [, reverse] [, loop])

Focuses the next item in the tab order.

Locates the first element in items that has a cq-focused attribute. If an element is found, the attribute is removed from all elements in items, and cq-focused is applied to the element that follows (in the tab order) the element that was found.

If no elements are found with the cq-focused attribute, the attribute is applied to the first element in items (last element if reverse is true). If the last element in items (first element if reverse is true) is found to have the cq-focused attribute, focus remains on that element. Unless loop is set to true, then focus is applied to first element.

Parameters:
Name Type Argument Description
items NodeList

A list of elements that are selectable via keyboard navigation.
reverse boolean <optional>

If true, the operation is performed in reverse order; that is, from the last element in items to the first.
loop boolean <optional>

Loops back to the first item if the last element in items is selected.
Since:

  • 8.4.0 Added loop parameter. Return element, instead of true, if focus is changed.

Inherited From:
Overrides:
See:
Returns:

The newly focused element if a cq-focused attribute has changed.

Type
HTMLElement | undefined

getChartContainer( [el])

Searches the DOM for the chart container element. Begins the search with el (or this) and proceeds parent-by-parent up the ancestry tree until an element is found.

Parameters:
Name Type Argument Description
el HTMLElement <optional>

The element on which to start the search. If not provided, this is used.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The chart container element or undefined if an element is not found.

Type
HTMLElement | undefined

getContextContainer( [el])

Searches the DOM for the chart context element. Begins the search with el (or this if el is not provided) and proceeds up the ancestry tree until an element is found or the root of the tree has been reached.

Parameters:
Name Type Argument Description
el HTMLElement <optional>

The element on which to start the search. If not provided, this is used.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The chart context element or undefined if an element is not found.

Type
HTMLElement | undefined

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

inputEntry(node, cb)

Attaches a keyboard input entry event.

Parameters:
Name Type Description
node HTMLElement

The element to which the input entry event is attached.
cb function

The callback function invoked when input entry occurs.
Inherited From:
Overrides:

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 default-position attribute of the <cq-message-toaster> element.
type string <optional>
 "info"

Toast style: "info", "error", "warning", or "confirmation". Overrides the default-transition 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 default-display-time 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

qs(path, context)

Adapts the querySelector method.

Parameters:
Name Type Description
path String

The CSS selectors for which to search.
context HTMLElement | String

The chart context element, which is the starting point of the DOM query, or "thisChart" to indicate the chart context in which this function is called.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The selected DOM element or undefined if an element is not found.

Type
HTMLElement | undefined

qsa(path, root, bustShadowRoots)

Adapts the querySelectorAll method. Returns an array instead of a node list to enable chaining of the array map, filter, forEach, and reduce functions.

Parameters:
Name Type Description
path String

The CSS selectors to find.
root HTMLElement | String

The root element, which is the starting point of the DOM query, or "thisChart" to indicate the chart context in which this function is called.
bustShadowRoots boolean

Set to true to penetrate shadow root boundaries.
Since:
  • 7.5.0
  • 8.9.0 Added bustShadowRoots parameter
Inherited From:
Overrides:
Returns:

An array of selected DOM element.

Type
Array.<HTMLElement>

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 HTMLElement

The toast to recall.
Since:

  • 8.2.0

removeClaim()

Remove a claim on keystrokes.

Inherited From:
Overrides:

removeFocused(items)

Removes the cq-focused attribute from all elements in items.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
Since:

  • 8.3.0

Inherited From:
Overrides:

removeMessageNode(messageNode [, reason])

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

Parameters:
Name Type Argument Description
messageNode HTMLElement

The toast to remove from the display queue.
reason string <optional>

The reason for the removal. Ex: "click" or "timeout".
Since:

  • 8.2.0

setContext(context)

Called for a registered component when the context is constructed. Sets the context property of the component.

Parameters:
Name Type Description
context CIQ.UI.Context

The chart user interface context.
Overrides:

setContextHolder()

Stores the component in the context holder (an array associated with the cq-context element) so that when the context is started, it knows that this tag is contextual.

Designed to be used as a helper method for the included WebComponents. A full tutorial on how to work with and customize the WebComponents can be found here: Web Component Interface.

Inherited From:
Overrides:

trimInnerHTMLWhitespace()

Returns a copy of the innerHTML of an element, with leading and trailing characters stripped. The following characters are stripped: newline, carriage return, tab.

Since:

  • 9.1.0

Inherited From:
Overrides:
Returns:

Trimmed innerHTML

Type
String