ListSelector Component Reference

Related documents

• Component Overview
• Component Reference
• Built-in Components
• Template Markup Language (TML) Reference

Table of Contents

• Introduction
• Attributes
• Instance methods
  • Inherited methods
  • setValue()
• Children
• DOM element properties

Introduction

Syntax

tml`
	<ListSelector />
`

The ListSelector component is a Selector component (it extends SelectorBaseCmp) that renders a <ul> with a list of selectable items. The items may have one level of sub-items, in which case the list expands to show the sub-items when selected ("accordions"). Only one group of sub-tiem can be expanded at one time. If another group is selected, the previous one collapses.

If the ListSelector component has a timeout attribute, an expanded group will automatically collapse after the specified amount of time.

Attributes

• Standard properties
  The ListSelector component accepts the standard attributes.
• onClick
  A function to call when an item is selected. The function has the signature fn(value) where value is the value associated with the selected option. The displayed list reflects the newly selected option. The function may subsequently override the selection by setting calling the setValue() method if required.
• options
  An array of options. The options are presented to the user in the same order. Each element must be an object (plain strings and numbers are not accepted by the options attribute; they are converted to {value, text} objects only when options are passed to setOptions()). An element contains the following properties:
  • options
    If the element object has an options property, it is an accordion group and its text is the group heading. The options property must contain an array of objects containing both a text property and a value property.
  • text
    The text to display for the option. text does not default to value, so it should always be supplied.
  • value

    The value of the state variable if this option is selected.
  

  An option whose value is the empty string is not displayed.

• onClickThru
  A function to call, with the current value, when an already selected item is clicked. If defined, every item shows a &rightChevron; symbol to indicate that more information is available on a second click.
• showSelection
  If truthy, the currently selected item is highlighted.
• timeout
  A positive numeric value. If valid, then the display of second-level options will be closed if no selection has been made within timeout milliseconds.
• value
  The value of the initially selected option in the options array.
• disabled
  Has no effect when given as an attribute: the base constructor removes it and the list never reads it, so clicks are never blocked.

Instance methods

These methods are intended to be used by parent components to dynamically change the properties of the rendered components without re-rendering.

Inherited methods

• Component methods

setValue()

Syntax

setValue(value)

Sets the rendered element's value.

Parameters

• value
  Any option value (the value of one of the options). The list is remounted so the highlight reflects the new value.

Children

The ListSelector component ignores any children.

DOM element properties

• The ListSelector component renders a <div style="overflow-y:auto"> wrapping a <ul> elemment containing a <li> element for each option.
• The wrapping <div> has a CSS class string that contains listSelector (and any className attribute). The <ul> has no class.
• An <li> element is rendered for each option. Each <li> element has a CSS class string that contains listSelector_item.
• The highlighted <li> element (only when showSelection is truthy) will have a CSS class string that contains listSelector_item-selected. The others will have listSelector_item-unselected.
• An accordion group header is an <li> with the class listSelector_accordionItem and listSelector_item-sel (collapsed group containing the selected item, when showSelection is truthy) or listSelector_item-unsel, containing a listSelector_caret chevron. An expanded group is followed by a <ul class="listSelector_sub"> of its items.