API Reference
Namespaces
Classes
Events
Global
Externals

Class: Lookup

WebComponents. Lookup

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

<cq-lookup>

This component presents a search input for the user to enter either a ticker symbol or a part of the symbol's description. Results of the search are presented in a dropdown for the user to choose.

A CIQ.ChartEngine.Driver.Lookup must be connected to this web component. The lookup driver searches financial exchanges for symbols that match the text entered in the component's input field.

The symbol lookup can be toggled using the Ctrl+Alt+S keystroke combination (see the symbolLookup action in hotkeyConfig.hotkeys in js/defaultConfiguration.js).

A default lookup driver is specified in the chart configuration object (see the Chart Configuration tutorial).

You can provide a different driver in the following ways:

Note: If the lookup component is unable to access a lookup driver, the component's input field is active, but the component does not produce results.

Keyboard control

When selected with tab key navigation and activated with Return/Enter, this component has the following internal controls:

  • Up/Down arrow — Move selection between search input, filters, and search results
  • Left/Right arrow — Switch between search result filters

Attributes

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

attribute description
cq-keystroke-default Enables the component to respond to keystrokes when the lookup input field does not have focus.

Warning: This feature may conflict with keyboard shortcuts set in other components.
cq-uppercase Forces text to uppercase.
cq-exchanges Comma-delimited list of financial exchanges searched by the lookup driver. Overrides the exchanges parameter of CIQ.ChartEngine.Driver.Lookup.

In addition, the following attributes are also supported:

attribute description
cq-keystroke-claim Enables processing of keyboard input.

Emitters

A custom event will be emitted by the component when a search is performed. 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 "search"
action "input"
value search string
filter filter
exchanges exchange list

A custom event will be emitted by the component when a result is selected. 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 "select"
action "click"
data symbol or symbolObject

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.

Customization

  • To hide the lookup results window, modify the CSS as follows:
.stxMenuActive cq-lookup-results { opacity: 0 }
  • To preload default results (rather than an empty result pane) on initial load, set an onChartReady handler in the chart configuration object (see the Chart Configuration tutorial); for example:
config.onChartReady = (stx) => {
    const defaultResults = [
        {
            "display": ["KW", "Kennedy - Wilson Holdings Inc", "NYSE"],
            "data": {
                "symbol": "KW",
                "name": "Kennedy - Wilson Holdings Inc",
                "exchDisp ": "NYSE"
            }
        },
        {
            "display": ["RWR", "SPDR Series Trust - SPDR DJ Wilshire REIT ETF", "NYSEArca"],
            "data": {
                "symbol": "RWR",
                "name": "SPDR Series Trust - SPDR DJ Wilshire REIT ETF",
                "exchDisp": "NYSEArca"
            }
        }
    ];

    const UISymbolLookup = document.querySelector(".ciq-search cq-lookup");
    UISymbolLookup.results(defaultResults);
}
  • The placeholder is programmatically set based on the width of the chart. On larger screens "Enter Symbol" is used, but on smaller screens only "Symbol" is used. As such, it is not sufficient to set a placeholder value on the HTML, as it will be overwritten by the Web Component logic. The following script will update the placeholder according to breakpoint values set in placeholderMapping. It should be placed inside the onWebComponentsReady callback provided in the defaultConfiguration object to ensure it is executed once all Web Components have been properly initialized. The approach here is to add a second breakpoint channel listener for the lookup component that overwrites the value set by default in the library.
function setLookupPlaceholders(placeholderMapping = {
    "break-lg": "Change symbol",
    "break-md": "+ symbol",
    "break-sm": ""
 }) {
  Array.from(uiContext.topNode.querySelectorAll('cq-lookup'))
  .forEach(el => {
        const { channels = {} } = el.context.config;
        el.channelSubscribe(
           channels.breakpoint || "channel.breakpoint",
           (breakPoint) => {
                    const symbolValue = placeholderMapping[breakpoint] || "Change symbol";

                    const symbolInput = el.querySelector("input");
                    symbolInput.setAttribute("placeholder", symbolValue);
         );
       });
    });
}
setLookupPlaceholders();

<protected> new Lookup()

Since:
  • 4.0.0 Added optional cq-uppercase attribute.
  • 7.4.0 Added optional cq-exchanges attribute.
  • 8.3.0 Enabled internal keyboard navigation and selection.
  • 9.1.0 Observes attributes. Added emitter.
Example

Markup for lookup component

<cq-menu class="search ciq-lookup-icon" cq-focus="input" icon="ciq">
		<cq-lookup cq-keystroke-claim cq-uppercase cq-exchanges="XNYS,XNAS,forex"></cq-lookup>
</cq-menu>

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.

Type:
  • String

Methods

acceptText(value, filter)

Performs the search of symbols based on the parameters input.

With the decoupling of the uiHelper to the Lookup.Driver you must be sure to include both an argument for maxResults and the closure to handle the results. maxResults must either be a number or a string to result in default value of 100.

Parameters:
Name Type Description
value string

String to search for.
filter string

Name of exchange to limit results to. The valid names are implementation-specific.
Since:

  • 3.0.0

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:

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:

chooseResult(params)

Closes the results list dropdown and passes the chosen symbol to be loaded onto the chart.

Parameters:
Name Type Description
params object
Properties
Name Type Description
node HTMLElement

The element within the results list containing the chosen result.

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:

close()

Closes the results list dropdown.

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:

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

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

forceInput()

Takes whatever was input in the search box and uses it as the symbol to load the chart.

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

initialize()

Creates the markup of the component, and sets up event handlers.

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:

isActive()

Returns active state of the search input box.

Returns:

True if active

Type
boolean

keyStroke(hub, key, e, keystroke)

Handler for keyboard interaction.

Note that this captures keystrokes on the body. If the input box is focused then we need to allow the input box itself to handle the strokes but we still want to capture them in order to display the lookup results. We first check activeElement to see if the input is focused. If so then we bypass logic that manipulates the input.value. In order make sure that the lookup menu is responding to an up-to-date input.value therefore we have to put all of those pieces of code in setTimeout(0)

Note that when comparisons are enabled, there are two Lookup components on the screen. Each keypress will therefore pass through this function twice, once for each Lookup component. Only the active component will process the keystroke.

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
keystroke CIQ.UI.Keystroke

Contains status of function keys
Returns:

true if keystroke was processed

Type
boolean

onKeyboardDeselection()

Handler for when losing keyboard focus.

onKeyboardSelection()

Handler for when gaining keyboard focus.

open()

Opens the results list dropdown.

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>

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()

Clear out the input and results list.

results(arr)

Displays an array of results returned by the CIQ.ChartEngine.Driver.Lookup.

Each element in the array should be in the following format (see CIQ.ChartEngine.Driver.Lookup#acceptText):

{
    display: ["symbol ID", "symbol description", "exchange"],
    data: {
        symbol: "symbol ID",
        name: "symbol description",
        exchDis: "exchange"
    }
}

The lookup component by default displays three columns as represented by the array. The data object can be a format required by your quote feed, or it can be a simple string if you just need to support a stock symbol.

Parameters:
Name Type Description
arr Array.<object>

The array of results.

selectItem(data, fn)

Accepts a new symbol or symbol object.

Parameters:
Name Type Description
data object

Contains a symbol or symbol object in a form accepted by CIQ.ChartEngine#loadChart.
fn function

Function to execute when the callback set by setCallback finishes.
Since:

  • 8.2.0 Removed the params parameter. Added the fn parameter.

setCallback(cb)

Sets a callback function to be called when the user selects a symbol.

Parameters:
Name Type Description
cb function

The callback function; for example, an implementation of CIQ.UI.Context#changeSymbol.

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:

setDriver(driver)

Connects a CIQ.ChartEngine.Driver.Lookup to the web component.

The lookup driver searches financial exchanges for symbols that match the text entered in the component's input field.

Parameters:
Name Type Description
driver CIQ.ChartEngine.Driver.Lookup

The lookup driver to connect to the web component.

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