Selector Component Reference

Related documents

• Component Overview
• Component Reference
• Built-in Components
• Template Markup Language (TML) Reference
• Selector Input State Variable Reference

Table of Contents

• Introduction
  • Radio buttons
• Attributes
• Instance methods
  • getText()
  • setClassName()
  • setDisabled()
  • setOptions()
  • setValue()
• Children
• Base class
• DOM element properties

Introduction

Syntax

tml`<Selector .../>`

The Selector component renders selector inputs. It is a separate component used by the Selector Input State Variable Reference so that it can be reused by other components.

The Selector component normally selector field that shows and currently selected value and will show a popup scrollable list of options when clicked. The HTML <select> element is not used because the presentation can be highly variable between platforms.

The Selector component has several methods that can be used to allow parent components to dynamically manipulate the state of the rendered elements. See [Instance methods](#instance methods).

Radio buttons

If the radio attribute is truthy, the options are presented as a set of radio buttons. The radio buttons can be laid out horizontally with button labels on the top or bottom, or vertically with the button labels to the left or right. The layout is controlled by the orientation attribute. The button labels are the test associated with each option.

Attributes

• Standard properties
  The Selector component accepts the standard attributes.
• disabled
  If present and truthy, the selector is intended to appear greyed out and not be user-changeable. Note that the disabled attribute is removed by the base class constructor, so it is not applied initially (the popup selector reads it from the removed props and the radio selector never reads it). Use setDisabled() to disable a selector after it is mounted.
• onUserChange
  A function to call when the user changes a selection. The function has the signature fn(value) where value is the value associated with the selected option. It is called when the user picks an option from the popup list or a radio button. The displayed list reflects the newly selected option. The onUserChange function may, of course, 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 containing the following properties:
  • text
    The text to display for the option. text does not default to value when options are given by the options attribute.
  • value

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

  Plain strings and numbers are not normalized when passed in the options attribute. They are normalized only by setOptions(), which converts a string or number element to an object whose value is the element and whose text is the element coerced to a string.

• orientation
  Controls the layout of the radio button. If the radio attribute is not truthy, orientation is ignored. The button labels are the test associated with each option. The possible values are:
  • labelBottom (default)
    The radio buttons will be laid out horizontally with the button labels below each button.
  • labelLeft
    The radio buttons will be laid out vertically with the button labels to the left of each button.
  • labelRight
    The radio buttons will be laid out vertically with the button labels to the right of each button.
  • labelTop
    The radio buttons will be laid out horizontally with the button labels above each button.
• radio
  If present and truthy, the options will be displayed as a set of horizontal or vertical radio buttons. The orientation is controlled by the orientation attribute. If no orientation is specified, the radio buttons will be laid out horizontally with the labels below each button.
• value
  The initial selected value.
• valueOnly
  If present and truthy, the selected text will be displayed as inline text and will not be user-changeable.

Instance methods

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

getText()

Syntax

getText()

Returns the text associated with the currently selected option.

Return value

A String.

setClassName()

Syntax

setClassName(cn)

Sets the rendered element's className to cn.

Parameters

• cn
  A CSS class string.

setDisabled()

Syntax

setDisabled(b)

if b is truthy, the selector input is disabled and appears greyed out. If b is falsey, the selector input is enabled. This has no effect on a valueOnly selector.

Parameters

• b
  A Boolean.

setOptions()

Syntax

setOptions(options)
setOptions(options, value)

Sets the component options according to the array in options and remounts the component. If value is present, then the selected option value is set to value after the options are set. Calling setOptions() with no options makes no change.

Return value

The component's current array of (normalized) options.

Parameters

• options
  An array of options. The options are presented to the user in the same order. Each element can contain a string, a number, or an object. If an element is an object, it is used as is and must contain the following properties:
  • text
    The text to display for the option.
  • value

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

  If an element is a string or a number, the option's value is the element and its displayed text is the element coerced to a string.

• value (optional)
  The value of the selected option in the options array.

setValue()

Syntax

setValue(value)

Sets the rendered element's value.

Parameters

• value
  Any option value (the value of one of the options).

Children

The Selector component ignores all children.

Base class

The value-only, popup and radio renderings all extend the exported SelectorBaseCmp class (also the base class of ListSelector). SelectorBaseCmp removes the options, value and disabled attributes from the component props, keeps them in _options, _value and disabled, and implements setValue(), getText() and setOptions().

DOM element properties

The Selector is rendered in several different ways:

• If the valueOnly attribute is truthy:
  The text associated with the selected value is rendered in a <span> element. The element will have selector_value and selector_value-valueOnly CSS class strings.
• If the valueOnly and radio attributes are not truthy:
  The selector is rendered as an outer, classless <span> containing a <span> and a <div>:
  • The first inner <span> has the CSS class strings passed in the className attribute plus popupInput, selector, selector_wrapper and, when disabled, input-disabled. Clicking it opens the popup list. It contains two <span> elements:
    • A <span> with a CSS class name of selector_value containing the currently selected option text.
    • A <span> with a CSS class name of selector_symbol containing the selector glyph.
  • The <div> has the CSS class strings selector_optContainer and selector_optContainer-hide or selector_optContainer-show. It contains the scrollable popup list of option text (a selector_optWrapper <div> containing a <ul class=selector_optList> of <li class=selector_optItem> elements, each with selector_optItem-sel or selector_optItem-unsel) that appears over the input field. The popup list disappears when an option is selected, when the area outside the list is clicked, or after 10 seconds.
• If the valueOnly attribute is not truthy and radio attribute is truthy:
  • The options are rendered in a Table component with radio buttons and labels in the desired orientaion.
  • The className, radioInput and orientation classes are intended for the Table, but the current implementation does not pass them on to it.