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()
  • setDflt()
  • setSavedState()
  • 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. A value that matches an option is valid. A value that matches no option is valid only while the options list is still empty, 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. Once the options are set, a value that is not one of them is invalid. In every case undefined (while there are options), NaN, and Error instances are invalid.

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 SelectorInputSvCmp (an exported class), which renders the Selector component, supplies it the current options and value, and replaces the options in the Selector when the options child state variable changes.

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)

Returns false if the value is an Error, NaN, or undefined while options exist. Otherwise returns true if the value is present in the options. If it is not present in the options, returns true only if the selector is dynamic (isStatic is false) and the options list is empty. 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 value is present, the state variable is set to it, and if the dflt value is not present in the updated options, dflt is set to value.

If value is not present and the current state variable value is not valid for the new options, the dflt is first changed to the first option value if the current dflt is not among the options, and then the state variable is set to dflt. A valid current value is left unchanged.

If opts is empty, the options are cleared, dflt is set to undefined, and the state variable value is set to undefined.

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.

setDflt()

Syntax

setDflt()

Sets the state variable to its default value. For a dynamic selector (isStatic is false) that was constructed with info.options, the options may have been narrowed by later options() calls, which can also have replaced dflt. In that case setDflt() first restores dflt from info.dflt (if specified) and the original info.options, so a reset always returns the declared default.

setSavedState()

Syntax

setSavedState(value)

Sets the state variable from a value restored from storage. If value is undefined, the default is set. For a static selector, a saved value that is not one of the options is bad data; it is logged and the default is set. For a dynamic selector the value is accepted as is, since the options may not yet be set; it is checked again when the options are set.

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_Selector'.