API Reference
Namespaces
Classes
Events
Global
Externals

Class: Toggle

WebComponents. Toggle

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

<cq-toggle>

When tapped/clicked, this component will toggle through different states. Each state represents a value of an object's member; for example, the object could be the chart's layout or preferences, while the member could be a property of these objects. If the member attribute of the toggle is set, the toggle state is bound to that member, meaning, if the underlying member value is changed, the toggle will change state to reflect that.

Use registerCallback to receive a callback every time the toggle changes. When a callback is registered, any automatic class changes are bypassed.

To bind the component's configuration, set its config attribute to an object in the CIQ.UI.Context.config.toggles object. Using a configuration allows easy customization of callback functions. See example below.

Attributes

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

attribute description
action If set to "class" (the default), will set/unset the "active" class on the component when executing callbacks.
config Key pointing to a configuration file entry which specifies the callback functions.
help-id A key to the correct help text in CIQ.Help.Content.
icon Class name for image to use for the toggle.
member Object member to observe. If not provided, then callbacks are used exclusively.
multichart-distribute Option for multichart context. Distributes object member change to all charts.
reader Accessibility text when focused by a screen reader.
stxtap Custom click handling which overrides the default toggling functionality.
toggles A comma-separated list of values which are toggled through with each click. The list can include "null". Stringified booleans and "null" are converted to their primitive values. All other values are passed to the Number constructor. If the result is a number (not NaN), the number is used. Otherwise the value is left as a string.
toggle-classes A comma-separated list of classes associated with the toggle setting. If a setting requires multiple classes, they need to be separated with spaces.
tooltip Text for the tooltip which appears when hovering over the component.
value The current state of the toggle.

In addition, the following attributes are also supported:

attribute description
active-class A class name to add to a binary state toggle if it is in an active state.

Emitters

A custom event will be emitted by the component when it is clicked. 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"
effect "toggle"
action "click"
value value

cause and action are set only when the value is changed as a direct result of clicking on the component.

This component comes with a default markup which is used when the component tag contains no other markup when it is added to the DOM. The default markup provided has accessibility features.

<protected> new Toggle()

Since:
  • 2015
  • 9.1.0 Observes attributes. Added emitter.
Examples

Toggle bound to layout.crosshair:

<cq-toggle member="layout.crosshair" reader="Crosshair" tooltip="Crosshair (Alt + \)" icon="crosshair"></cq-toggle>

Registering a callback function directly:

document.querySelector("cq-toggle").registerCallback(function(value){
   console.log("current value is " + value);
   if(value != false) this.classList.add("active");
});

Registering a callback function via the config:

// set the toggle component's config attribute to "example"
stxx.uiContext.config.toggles.example.callbacks = [function (value) {
   console.log("current value is " + value);
   if(value != false) this.classList.add("active");
}];

Extends

Members

<static> markup :String

Default markup for the component's innerHTML, to be used when the component is added to the DOM without any innerHTML.

This markup contains placeholder values which the component replaces with values from its attributes. Variables are represented in double curly-braces, for example: {{text}}. The following variables are defined:

variable source
reader from attribute value
icon from attribute value
help-id from attribute value
tooltip from attribute value
tooltip_class "hidden" if tooltip attribute not specified
help_class "hidden" if help-id attribute not specified
Type:
  • String

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:

begin()

Initializes the handler when the toggle is clicked. Called once when the context becomes available.

changeContext(newContext)

Called for a registered component when the context is changed in a multichart environment.

Parameters:
Name Type Description
newContext CIQ.UI.Context

The chart user interface context.

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:

connectObservable()

Sets up an observable if there is a member supplied in the attributes. Will remove any existing observable. The observable information is stored in the component instance's observeInfo property. If there is no member supplied in the attributes, you can still have the component observe an object's member manually by using the CIQ.UI.observeProperty function, but you should also set the observeInfo property so a proper cleanup can be performed when the component is disconnected.

Example
CIQ.UI.observeProperty("headsUp", stxx.layout, listenerFunction);
this.observeInfo = { member: "headsUp", obj: stxx.layout, listener: listenerFunction };

connectedCallback()

Convenience function that creates an array of injections for the component and sets a variable of node equal to self.

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:

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:

disconnectObservable()

Removes any observable set up by WebComponents.Toggle#connectObservable.

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:

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

fireConfigChange()

Forces config attribute to change, even if the value of the config attribute didn't change. This is useful if the underlying object representing the configuration did change.

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

getMarkup()

Formats the default markup, replacing any variables with the actual values provided by the attributes.

Returns:

The prepared markup

Type
string

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

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:

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>

registerCallback(fc, immediate)

Adds a callback function to the toggle.

Parameters:
Name Type Description
fc function

The callback function to add to the toggle. The function accepts the current value of the toggle as a parameter. The value of this within the callback function is the toggle component.
immediate boolean

A flag that indicates whether to immediately call the callback function after it has been registered with the toggle.
Since:

  • 2015

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:

reset()

Called when an attribute changes, will regenerate the toggle component, updating whatever needs to be updated as a result of the attribute change.

set(value)

Called when the toggle is activated through a click or change of the value attribute, will update whatever needs to be updated in the component as a result of the activation. This comprises the class and aria settings.

Parameters:
Name Type Description
value any

New value of toggle

setAriaPressed()

Sets the aria-pressed attribute based on the component's class. A class value of either active, on or off will set the aria value. A truthy value for the component's current value will also set the aria value.

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:

splitAndNormalize(input)

Formats the attribute values. By default, anything in the toggle attribute will be a string, which can cause issues when observing a member because "true"!==true. This function will set "true", "false", and "null" to be their native alternatives instead of strings. It also checks to see if it can cast the number and if it is not NaN it changes it to be a number. Be aware this will change an empty string to 0 but you shouldn't be setting an empty string!

Parameters:
Name Type Description
input any

Input string, possibly comma-delimited
Returns:

Formatted results, in an array and in their assumed type

Type
Array.<any>

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

updateClass()

Updates the toggle's class based on the current toggle value. Used when toggle has more than binary values.

updateFromBinding()

Updates the toggle's appearance when the member to which it is bound has changed value. For example, if the toggle controls the crosshair, if the crosshair value in the layout changes, this function will be called to keep in sync with the layout value.