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
• 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 will appear greyed out and will not be user-changeable.
• 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. 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 can contain a string, a number, or an object. If an element is an object, it must contain the following properties:
  • text
    The text to display for the option. If text is omitted, then value coerced to a string is used.
  • value

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

  If an element is a number, the displayed text is the number coerced to a string, and the value is the element. If an element is a string, it is used for both the displayed text and value.

• 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.

Parameters

• b
  A Boolean.

setOptions()

Syntax

setOptions(options)
setOptions(options, value)

Sets the component options according to the array in options. If value is present, then the selected option value is set to value after the options are set.

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 must contain the following properties:
  • text
    The text to display for the option. If text is omitted, then value coerced to a string is used.
  • value

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

  If an element is a number, the displayed text is the number coerced to a string, and the value is the element. If an element is a string, it is used for both the displayed text and value.

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

setValue()

Syntax

setValue(value)

Sets the rendered element's value.

Parameters

• value
  A Number.

Children

The Selector component ignores all children.

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 a <span> element containing two child <span> elements containing the text associated with the selected value and a selector glyph. When the outer <span> is clicked, a scrollable list of option text appears over the input field. The popup list disappears when an option is selected.
  • The outer <span> element has the CSS class strings passed in the className attribute plus popupInput and selector.
  • The <span> element containing the currently selected option text has a CSS class name of selector_value.
  • The <span> element containing selector glyph has a CSS class name of selector_symbol.
• 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 Table element has a CSS class name of radioInput.

XXX