# Class: BaseComponent ## [CIQ](CIQ.html)[.UI](CIQ.UI.html). BaseComponent () Abstract class for [WebComponents](WebComponents.html) using this framework. Provides a base set of functionality for web components. #### new BaseComponent() See: - [WebComponents](WebComponents.html) ### Extends - HTMLElement ### Members #### \ BaseComponent.className :string Name of the WebComponent class ##### Type: - string Since: - 9.8.0 ### 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. #### 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 | \ | 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 #### \ adoptedCallback() #### 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](CIQ.ChartEngine.html) | 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](CIQ.ChartEngine.html) | \ | 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](CIQ.ChartEngine.html) | A reference to the chart engine. | Since: - 7.5.0 ##### Returns: A callback invoked when unsubscribing from the channel. Type function \| undefined #### 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](CIQ.ChartEngine.html) | 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 #### deactivateItem(item) Blurs and removes the `cq-keyboard-active` attribute from `item`. ##### Parameters: | Name | Type | Description | |--------|-------------|-------------| | `item` | HTMLElement | | Since: - 8.4.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. ##### Example Listening for a custom event using the standard `addEventListener` method. ``` javascript document.addEventListener("DrawingPalette", (e) => { console.log(`Drawing Palette "view" is now: ${e.detail.view}`) }) // For a given component tag we can find name of the event to listen using: const componentEventName = CIQ.UI.components("cq-drawing-palette")[0].name; // If the document might have multiple chart context elements (cq-context), add the listener to the specific context element instead of the document itself. ``` #### 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 #### 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 #### 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 | \ | If true, the operation is performed in reverse order; that is, from the last element in `items` to the first. | | `loop` | boolean | \ | 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: - [focusItem](CIQ.UI.BaseComponent.html#focusItem) ##### 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 | \ | 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 | \ | 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. | #### \ makeTap(node, cb) Attaches an "stxtap" event to an element, which will be fired on any event that resembles a click or tap. Note only one stxtap event is allowed per element. The handler is saved on the element as the `selectFC` property. Designed to be used as a helper method for the included [WebComponents](WebComponents.html). A full tutorial on how to work with and customize the WebComponents can be found here: [Web Component Interface](tutorial-Web%20Component%20Interface.html). ##### Parameters: | Name | Type | Description | |--------|------------------------------------------------------------------------------------|---------------------------------------| | `node` | HTMLElement | The element to attach a tap event to. | | `cb` | [CIQ.UI.BaseComponent~makeTapCallback](CIQ.UI.BaseComponent.html#~makeTapCallback) | The callback when tapped. | #### 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.\ #### removeClaim() Remove a claim on keystrokes. #### 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 #### 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 ##### Returns: Trimmed innerHTML Type string #### \ bind(node \[, params\]) Set bindings for a node that has been created dynamically. The attribute can be either "stxbind", "stxtap" or "stxsetget". ##### Parameters: | Name | Type | Argument | Description | |----------|-------------|--------------|------------------------------------------| | `node` | HTMLElement | | The node to bind. | | `params` | object | \ | Parameters passed as the final argument. | Deprecated: - 7.0.0 See: - [CIQ.UI.BaseComponent.bindNode](CIQ.UI.BaseComponent.html#.bindNode) #### \ 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](WebComponents.html). A full tutorial on how to work with and customize the WebComponents can be found here: [Web Component Interface](tutorial-Web%20Component%20Interface.html). In the case of "stxsetget", a "set" and "get" will be prepended to the bound method. \.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), \.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 | \ | Parameters passed as the final argument. | Since: - 7.0.0 Previously [CIQ.UI.BaseComponent.bind](CIQ.UI.BaseComponent.html#.bind). - 8.2.0 Added return boolean. ##### Returns: true if binding succeeded; false if binding failed. Type boolean ##### Examples Look for the next parent with method `tool()`. ``` javascript stxtap = "tool('gartley')" ``` To explicitly target a web component, use a prefix. ``` javascript 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](WebComponents.html). A full tutorial on how to work with and customize the web components can be found here: [Web Component Interface](tutorial-Web%20Component%20Interface.html). 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 | \ | 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](CIQ.ChartEngine.html) | \ | A reference to the chart engine. | | `self` | object | \ | 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 empty object if the path is not provided or if one of `stx` or `self` is not provided. Type object #### \ 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](WebComponents.html). A full tutorial on how to work with and customize the WebComponents can be found here: [Web Component Interface](tutorial-Web%20Component%20Interface.html). ##### Parameters: | Name | Type | Argument | Description | |-------------|-------------|--------------|-------------------------------------------------------------------------------------------------------------------| | `node` | HTMLElement | | A node with either the `stxbind` or `stxtap` attribute. | | `binding` | string | \ | 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](CIQ.UI.Helper.html) \| undefined #### \ 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 ### Type Definitions #### makeTapCallback(e) ##### Parameters: | Name | Type | Description | |------|------------|-------------| | `e` | TouchEvent | TouchEvent |