API Reference
Namespaces
Classes
Events
Global
Externals

Class: Dialog

WebComponents. Dialog

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

<cq-dialog>

Manages general dialog interaction such as display, hide, location, size, tap interaction, etc.

Attributes

This component observes the following attributes and will change behavior if these attributes are modified:

attribute description
cq-title Display text in dialog heading.
cq-description Optional description of dialog.
cq-close-button Set to "false" to hide the close (X) button in uppper right corner. Note: Users can still close the dialog by clicking outside of it or pressing the Esc key.

Initial attribute values can be configured in the context configuration.

Emitters

A custom event will be emitted by the component when it is opened or closed. 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
effect "hide", "show"
title heading of dialog
type tag name of dialog being wrapped

<protected> new Dialog()

Since:
  • 9.1.0 Observes attributes. Added emitter.
Examples

A dialog container

<cq-dialog cq-timezone-dialog>
		<cq-timezone-dialog>
		 ...
		</cq-timezone-dialog>
	</cq-dialog>

Configuring the attributes

stxx.uiContext.config.dialogs.timezone = {
		tag: "cq-timezone-dialog",
		attributes: {
			"cq-title": "Choose Timezone",
			description: "To set your timezone use the location button below, or scroll through the following list..."
		}
	];

Extends

Methods

addActiveAttribute(attribute)

Creates a new attribute to be activated when the dialog is open. Use this to style the dialog. This is automatically set by any component that is derived from DialogContentTag.

Parameters:
Name Type Description
attribute string

The attribute to add or remove
Since:

  • 4.1.0

Example
<style> cq-dialog[cq-study-context]{ padding:0; } </style>
<cq-dialog cq-study-context></cq-dialog>

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:

clickItem(item, e, originationElement)

Click a keyboard selectable element.

Parameters:
Name Type Description
item HTMLElement

Element to click.
e Event

The keystroke event.
originationElement HTMLElement

The keyboard active element which initiated the click.
Overrides:
  • CIQ.UI.BaseComponent#clickItem

close( [propagate])

Close the dialog and make it inactive. Calls the onClose() function if it is defined on this component.

Parameters:
Name Type Argument Description
propagate boolean <optional>

True if child elements should also call onClose functions

closeActiveMenu()

Close the active menu.

Returns:

returns true if a menu was closed.

Type
boolean

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:

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:

enableMultichartColorPickerFloat( [val])

Configure CSS layering to enable the color picker to float above the dialog.

Parameters:
Name Type Argument Default Description
val boolean <optional>
 true

Setting "val" to false will restore the original style values of the element.
Since:

  • 9.3.0

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

getKeyboardSelectableItems()

Returns an array of dialog elements that are keyboard selectable.

Returns:

An array of DOM elements

Type
NodeList

handlePropertyChange(name, oldValue, newValue)

Processes attribute changes. This is called whenever an observed attribute has changed.

Parameters:
Name Type Description
name string

Attribute name
oldValue string

Original attribute value
newValue string

new Attribute value

hide()

Hide the dialog.

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:

keyStroke(hub, key, e)

Handle the keystroke event to keyboard navigate the dialog. Tab and Enter are supported.

Parameters:
Name Type Description
hub CIQ.UI.KeystrokeHub

The hub that processed the key
key string

Key that was stroked
e Event

The event object
Returns:

true if keystroke was processed

Type
boolean

onKeyboardDeselection()

If we're using keyboard navigation, returns the highlight to the tab selected element. Called when dialog is no longer keyboard navigable.

onKeyboardSelection()

Hides the highlight on select because the study dialog contents re-render quite often, throwing off the highlight position (e.g. When a dropdown selection is made). Called when dialog becomes keyboard navigable

open(params)

Open the dialog.

Parameters:
Name Type Description
params object

Dialog parameters

Properties
Name Type Description
caller HTMLElement

The HTML element that triggered this dialog to open

processEsc(hub)

Handle escape key press.

Parameters:
Name Type Description
hub CIQ.UI.KeystrokeHub

The hub that processed the key.
Returns:

returns false if nothing was done.

Type
boolean

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>

refreshFocus()

Finds the first element in items that has a cq-focused attribute or a name attribute that matches the value of activeElementName. If found, that element is focused.

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:

resize()

Handles dialog resizing. Resizes child cq-scroll elements. Centers the dialog.

setTitle(title)

Forces a title change, even if the title is the same as before. Use this method to change the title of the dialog rather than just changing the cq-title attribute;

Parameters:
Name Type Description
title string

New title

show( [params])

Show the dialog. Use X,Y screen location (pageX, pageY from an event) for where to display context menus. If the context menu cannot fit on the screen then it will be adjusted leftward and upward by enough pixels so that it shows.

Parameters:
Name Type Argument Description
params object <optional>

Parameters

Properties
Name Type Argument Default Description
bypassOverlay Boolean <optional>
 false

If true will not display the scrim overlay
x Number <optional>

X location of top left corner. Use for context menus, otherwise dialog will be centered.
y Number <optional>

Y location of top left corner. Use for context menus, otherwise dialog will be centered.

stxContextMenu()

Set context menu position to mouse location.

tap(e)

Tap event handler for dialog. Prevents touch and mouse events from propagating outside of the dialog.

Parameters:
Name Type Description
e Event

tap event

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