API Reference
Namespaces
Classes
Events
Global
Externals

Class: Dropdown

WebComponents. Dropdown

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

<cq-dropdown>

This component is a container of menu options which can be scrolled though and selected. The component is typically revealed after a cq-menu component is opened. This component is usually nested within a cq-menu tag. The items that are listed in the dropdown are specified in a configuration. See example below. To bind the component's configuration, set its config attribute to an object in the CIQ.UI.Context.config.menus object.

This component automatically allows for scrolling through its elements, when the size of the list exceeds the dropdown's dimensions.

Attributes

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

attribute description
maximize Set to true to have the dropdown extend in height to the height of the chart container even when there are not enough items in the dropdown to fill it.
noresize Set to true to prevent resizing of dropdown. Otherwise, sizing is based on number of elements in the dropdown.
config Key pointing to a component configuration entry which specifies the content items.

If no markup is specified in this component, a default markup will be provided. It is strongly suggested to allow the default markup to be used. In order to use the default markup, the selections in the menu must be configured in the context configuration file and specified by key in the config attribute. See example.

Emitters

A custom event will be emitted by the component when an item in the component is toggled, selected, or edited. 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", "select", "edit"
action "click"
menu menu element which owns this component
params properties set in configuration object for the item specified by the action

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.

Configuration

Configuration is accomplished by setting up an object within the context configuration's menus object. Each menu dropdown is assigned a unique name which is itself an object property of the menus object. This property name is used as the value of the config attribute of the owning menu component. Let's call the object containing the configuration items. items will contain a property called content whose value is an array. Each array element is an object which represents one item in the dropdown. Let's call one of these array elements, item. Each item has several properties which describe the nature of the dropdown item to display. The following table of properties describes what they mean.

property description
type Describes what type of item to display. Valid values are described in the table below.
label Text to display.
className Optional class name to apply to item.
active Set to true to manually set the active state on the item. Note the active state is usually set with a bound value.
tap Name of helper function to execute when item is clicked.
setget Same as tap except used to bind values when type is radio, switch, or checkbox.
bind Name of helper function to execute when binding has changed. This is not a common option.
options Name of helper function to execute when clicking the options icon, which only appears when this property is set.
iconCls Optional class name of an icon to display on the item.
value Array of arguments to pass to tap, stxget, or bind functions; or, name of component when type="component".
feature Name of add-on to which this option belongs. If the add-on is not loaded, the option will not appear.
attributes Object containing attributes for a type="component" item.
selector Used to specify the selector for type="clickable".
method Used to specify the method for type="clickable".
menuPersist Normally menus close when selecting any item type besides checkbox or switch. Setting this property to "true" will keep the menu from closing after selection.
filterFor A label to specify the element to filter. The element to filter must also have its filter-name attribute set to this value. If filter-for is omitted, will filter this element's next sibling.
filterMin The number of filterable records below which the filter input will not appear. If omitted, filter input will never appear.
helpId A key to the correct help text in CIQ.Help.Content.

Valid types are described here:

type description
item Standard text which when clicked will execute tap or setget action via a helper.
switch Same as item except value is bound and displayed with a slider switch.
checkbox Same as item except value is bound and displayed with a checkbox.
radio Same as item except value is bound and displayed with a radio.
clickable Embeds a cq-clickable which executes an action, usually opening a dialog.
heading Unclickable text displayed in <h4> tag. May be configured to allow filtering of another element's items.
template Embeds markup specified with a name attribute equal to this component's value attribute. The markup to be embedded needs to be found in the document within a unique template which has the attribute cq-dropdown-templates.
component Embeds a component specified by value with attributes specified by attributes.
separator Unclickable horizontal line, used to separate two menu sections.
Since:
  • 9.1.0 This new component supersedes cq-menu-dropdown component.
Examples

Dropdown tag:

<cq-dropdown config="example"></cq-dropdown>

Sample configuration for the above dropdown tag:

stxx.uiContext.config.menus.example = {
		content: [
			{ type: "radio", label: "Show Dynamic Callout", setget: "Layout.HeadsUp", value: "dynamic" },
			{ type: "radio", label: "Show Tooltip", setget: "Layout.HeadsUp", feature: "tooltip", value: "floating" }
			{ type: "switch", label: "Minimal Tooltip", setget: "Layout.HeadsUp", feature: "tooltip", value: "minimal" }
		]
};

Template example:

<!--
Given a configuration item as follows:
{ type: "template", value: "my_template" }
-->
<template cq-dropdown-templates>
		<div name="my_template">
			<span>Custom Dropdown Item</span>
		</div>
</template>

Extends

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:

bind(elem, evtType)

Sets up the binding for the dropdown item.

Parameters:
Name Type Description
elem HTMLElement

Dropdown item to bind.
evtType string

Type of event to emit when the item is clicked.

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:

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:

disablekeyboardNavigation()

Remove keyboard navigation when item is clicked and its owning menu is hidden.

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

handlePropertyChange(name, oldValue, newValue, force)

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
force boolean

Set to true to force handling even if old value is the same as new value
Since:

  • 9.8.0 added force parameter

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)

Handler for keyboard interaction. Arrow keys move around the dropdown, while Space or Enter will select.

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

makeComponent(name [, attributes])

Builds a dropdown item when the type="component". Called by WebComponents.Dropdown#populate.

Parameters:
Name Type Argument Description
name string

Component name.
attributes object <optional>

attribute settings for the component.

onKeyboardDeselection()

If using keyboard navigation, return the highlight to the tab selected element.

populate()

Creates the dropdown items by parsing the configuration object and using the default markup to create each item.

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:

resize()

Resizes a dropdown when the screen is resized, or even if the configuraton is reloaded to add or remove items.

scrollImplementation()

Gets the scroll implementation set in the UI configuration. This is used to scroll the dropdown, if found.

Returns:

The scrolling implementation

scrollToElement(item)

Sets the active dropdown item to a certain location. The dropdown will scroll if necessary.

Parameters:
Name Type Description
item HTMLElement

Element to scroll to.

setFocus(selector)

Sets the focus on a specific item in the dropdown.

Parameters:
Name Type Description
selector HTMLElement

Element to focus.

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

<static> itemTemplate(params)

Default markup generator for an item's innerHTML. This function is called for each item in the dropdown. Based on the parameters passed in, the appropriate markup is generated. This function is called by WebComponents.Dropdown#populate.

Parameters:
Name Type Description
params Object
Properties
Name Type Argument Description
type String

Type of item, e.g. item, heading, switch, etc.
active Boolean <optional>

Active state of item (applied as .ciq-active class)
className String <optional>

Class name of item
options String <optional>

Helper function to execute when the options icon is clicked
feature String <optional>

Name of add-on which when loaded, this item will become visible
helpId String <optional>

Name associated with help for this item
iconCls String <optional>

Class for the icon in the item
label String <optional>

Text for the item
bind String <optional>

Helper function for binding
tap String <optional>

Helper function for tapping
setget String <optional>

Helper function for tapping and binding
selector String <optional>

For clickable type, target selector
method String <optional>

For clickable type, target method name on the above selector
value Array | String <optional>

Parameter(s) to pass to the bind, tap, or setget functions. If these aren't supplied, value will be stored in a data attribute. The value is always available in the data-value attribute.
content String <optional>

For template type, the HTML corresponding to the template's name
filterMin Number <optional>

For heading type, the minimum number of records to allow filtering
filterLabel String <optional>

For heading type, the placeholder text that appears in the filter search input
filterFor String <optional>

For heading type, the element to filter should have its filter-name attribute set to this parameter's value.
Returns:

Markup for a single dropdown item.

Type
String