Selector Input State Variable Reference

Related documents

• State Variables Overview
• StateVar Reference
• Built-in State Variables
• Input SV Type Reference

Table of contents

• Introduction
  • Dynamic selectors
• Child state variables
• Constructor
• Instance methods
  • Inherited methods
  • findOption()
  • fmtVal()
  • hasOption()
  • isValid()
  • options()
  • optionTexts()
  • optionValues()
• Instance properties
  • Inherited properties
• isSelector (read only)
• isStatic
  • text (read only)
• Component attributes
  • Inherited attributes
• DOM element properties

Introduction

Selector Input state variables represent an input that allows the user to select from a series of options.

By default, the selector renders as a popup list of options for the user to select. The currently selected option is highlighted. The selector can also render as a set of radio buttons by specifying the radio attribute. The radio buttons can be horizontal or vertical, and the text labels can be on either side for both orientations by specifying one of the following attributes:

• labelTop
  A horizontal orientation with the selection text above the radio buttons.
• labelRight
  A vertical orientation with the selection text to the right of the radio buttons.
• labelBottom (default)
  A horizontal orientation with the selection text below the radio buttons.
• labelLeft
  A vertical orientation with the selection text to the left of the radio buttons.

The options are not saved when a Selector Input is saved to storage. Only the selector value is saved. It is expected that the app code will reestablish the current options and upgrade the saved values as required.

Dynamic selectors

A Selector Input's state variable options can be static. If so, the isStatic property is true. Any attempt to change the options of a static selector will cause an assertion failure. Additionally, the isValid method will return false if the value does not match an available option.

A Selector Input's options can be changed if the isStatic property is false. The selector input can have any value except undefined, NaN, or an Error instance, and it will still be valid because the correct options might be set later. This is especially important when the application state is restored at startup before model execution sets the options.

The isStatic property is set by default if options are provided during construction. If no options are provided, or if the provided options array is empty, it is set to false. If info.isStatic is specified during construction, it overrides the default setting. This allows the app to filter a provided info.options array later. The isStatic property can also be modified dynamically after initialization.

Child state variables

Selector Input state variables maintain a public child state variable that can be referred to using the subname options (e.g., myPage_mySelector_options). The child state variable's value is an array of options objects containing the following properties:

• text
  The text to display for the option.
• value
  The value of the state variable if this option is selected.

The child state variable can be used to determine when the state variable options change (as opposed to the state variable value).

Constructor

• Type string: 'selectorInput', class: SelectorInputSv

Syntax

ctl.createPage({
	...,
	stateVarInfo:[
		{type:'selectorInput', ...},
	],
})

Parameters

• info
  An object containing the state variable properties. The info object can contain the following properties, but subclasses of StateVar may have additional properties:
  • StateVar info properties.
  • Model SV type info properties.
  • Input SV type info properties.
  • options (optional)
    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 can contain the following properties:
    • text (optional)
      The text to display for the option. If text is omitted, then value coerced to a string is used.
    • value (required)

      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.

Instance methods

Inherited methods

• StateVar methods
• ModelValueSv methods
• InputSv methods

Note: The component() method returns a SelectorInputSvCmp.

findOption()

Syntax

findOption(value)

Returns an option object with the value.

Parameters

• value
  The value of the option to be searched for.

Return value

An object with the following properties:

• text
  The text displayed for the option.
• value
  The state variable value if this option is selected.

fmtVal()

Syntax

fmtVal()

Returns the displayed text for the current state variable value.

Return value

A String.

hasOption()

Syntax

hasOption(value)

Returns true if the value exists in the options.

Parameters

• value
  The value of the option to be searched for.

Return value

A Boolean.

isValid()

Syntax

isValid(value)

If value is present, returns true if value is present in the options or if the isStatic property is true and the value is not undefined, NaN, or an instance of Error. If value is not present, the currently selected value is used.

Parameters

• value (optional)
  The value of the option to be searched for. If not present, the current value of the state variable is used.

Return value

A Boolean.

options()

Syntax

options()
options(opts)
options(opts, value)

Sets or gets the state variable options. If opts is not present, the current options array is returned. Otherwise, the options are set according to the array in opts. If value is present, then the state variable value is set to value after the options in opts are set. If the state variable's isStatic attribute is true, then setting options is disallowed and will cause an assertion failure.

If the state variable's dflt attribute value is not present in the updated options, then it is set to value, if present, or to the first option value, if not present.

Parameters

• opts (optional)
  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 can contain the following keys:
  * text (optional)
  The text to display for the option. If text is omitted, then the text will be the value converted to a string.
  * value (required)
  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 to set the state variable after the options are set. If not specified, the value of the state variable is not modified.

Return value

An array of option objects, each containing the following properties:

• text
  The text to display for the option.
• value
  The value of the state variable if this option is selected.

optionTexts()

Return the list of option texts.

Syntax

optionTexts()

Return value

An array of option text strings.

optionValues()

Return the list of option values.

Syntax

optionValues()

Return value

An array of option options values.

Instance properties

Inherited properties

• StateVar properties
• ModelValueSv properties
• InputSv properties

isSelector (read only)

Always true for selectorInput.

Value

A Boolean.

isStatic

Set to true if the options cannot be modified.

Value

A Boolean.

text (read only)

The option text associated with the current state variable value.

Value

A String.

Component attributes

Inherited attributes

• Component attributes
• Selector attributes

DOM element properties

• Standard DOM element properties
• The selectorInput Component will render a <span> with the text associated with the current state variable value.
• When the element has focus a scrollable popup will display the list of optiona texts to select with the currently selected options highlighted.
• The <span> element will have a className that contains 'svIo_selectorInput'.