API Reference
Namespaces
Classes
Events
Global
Externals

Class: BaseComponent

CIQ.UI. BaseComponent

new BaseComponent()

Abstract class for WebComponents using this framework.

Provides a base set of functionality for web components.

See:

Extends

  • HTMLElement

Methods

bind()

Set bindings for a node that has been created dynamically. The attribute can be either "stxbind", "stxtap" or "stxsetget".

Deprecated:

  • 7.0.0

See:

bindNode(node [, params])

Set bindings for a node that has been created dynamically. The attribute can be either "stxbind", "stxtap", or "stxsetget".

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.

In the case of "stxsetget", a "set" and "get" will be prepended to the bound method. <Helper>.getXxxxx() is called once during this initialization. That method should set up a binding.

When tapping (or changing a value in the case of an input field), <Helper>.setXxxx() is called.

Bindings in web components search for the nearest parent component that contains the expected function (see the examples).

Parameters:
Name Type Argument Description
node HTMLElement

The node to bind.
params object <optional>

Parameters passed as the final argument.
Since:
Returns:

true if binding succeeded; false if binding failed.

Type
boolean
Examples

Look for the next parent with method tool().

stxtap = "tool('gartley')";

To explicitly target a web component, use a prefix.

stxtap = "DrawingToolbar.tool('gartley')";

buildReverseBindings( [traverseNode])

Travels the DOM tree and locates stxbind attributes.

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

UI elements can use these to configure menus or dialogs. To effect reverse binding, set the value of the stxbind attribute to a Helper class name and data element. For instance Layout.chartStyle.

The Helper element will seek out all children with stxtap attribution and examine the arguments to that function call for a match.

Parameters:
Name Type Argument Description
traverseNode HTMLElement <optional>

Specify the node to traverse. Defaults to topNode for the context.

getChannel(path [, stx] [, self])

Retrieves a channel object and property from the given path.

Parameters:
Name Type Argument Description
path *

The channel path.
stx CIQ.ChartEngine <optional>

A reference to the chart engine.
self Object <optional>

A component reference used to optionally obtain a reference to the chart engine.
Since:

  • 7.5.0

Returns:

An object containing the channel object and property name. Returns undefined if the path is not provided or if one of stx or self is not provided.

Type
Object | undefined

getHelper(node [, binding], attribute)

Locates the nearest UI helper for a given attribute. If none exists, then it is created at the top node of the chart context.

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.

Parameters:
Name Type Argument Description
node HTMLElement

A node with either the stxbind or stxtap attribute.
binding String <optional>

The type of binding or helper name being looked for, otherwise the stxbind and then stxtap attributes are queried
attribute String

Either "stxtap" or "stxbind". Only required if binding==null.
Returns:

A UI helper object.

Type
CIQ.UI.Helper

selfOrParentElement(startEl, classOrAttributeOrTag)

Searches the DOM for an element that has the CSS class, HTML attribute, or tag name (node name) specified in classOrAttributeOrTag.

Begins the search with startEl and proceeds up the ancestry tree until an element is found or the root of the tree has been reached.

Parameters:
Name Type Description
startEl HTMLElement

The element on which to start the search.
classOrAttributeOrTag String

The CSS class, HTML attribute, or node name for which to search.
Since:

  • 7.5.0

Returns:

The found element or undefined if an element was not found.

Type
HTMLElement | undefined

toPropAndObject(path, startObj)

Walks an object path by means of the elements of the path argument, excluding the last element. Starts the walk with startObj.

For example, if the path is "x.y.z.end" and the starting object is myObj, the function attempts to find myObj.x.y.z.

Parameters:
Name Type Description
path String

A string of dot-separated elements, such as "channel.breakpoint".
startObj Object

The initial object in the object path, such as an instance of CIQ.ChartEngine.
Since:

  • 7.5.0

Returns:

An object literal containing the last property in the path and an object referenced by the succession of the preceding path elements; for example, the path channel.breakpoint and an instance of the chart engine as the starting object would produce {"breakpoint", chartEngine.channel}. If any of the path elements (excluding the last) is not a property of the object path, the function returns an empty object ({}).

Type
Object

addClaim(helper)

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

Parameters:
Name Type Description
helper HTMLElement

The element that should claim a keystroke.

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

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

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

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

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

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

emitCustomEvent(params)

Emits a custom event from the webcomponent.

Parameters:
Name Type Description
params object
Properties
Name Type Argument Default Description
emitter HTMLElement <optional>

The element that will be emitting the event. Required if not provided in detail.
actualType string <optional>

The event type that represents the user's action. Required if not provided in detail.
listenType Object <optional>
 "click"

The event type to dispatch to a listener on the component.
detail Object <optional>
 {}

Optional extra parameters to include in the detail of the Custom Event.
Since:

  • 8.9.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

Returns:

The elements in items that have a cq-focused 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

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.

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

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

Returns:

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

Type
HTMLElement | undefined

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.

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

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
Returns:

An array of selected DOM element.

Type
Array.<HTMLElement>

removeClaim(helper)

Remove a claim on keystrokes.

Parameters:
Name Type Description
helper CIQ.UI.Helper

Helper or ContextTag from which the claim on keystrokes is removed.

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

setupShadow(root)

Copies stylesheets from the document root to the shadow root. Also flags itself as a shadow root in a way that it can be easily found.

Parameters:
Name Type Description
root ShadowRoot

The shadow root to set up.

deactivateItem(item)

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

Parameters:
Name Type Description
item HTMLElement
Since:

  • 8.4.0

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

Returns:

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

Type
Array