Data Selector Input State Variable Reference

Related documents

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

Table of contents

• Introduction
• Child state variables
• Constructor
• Instance methods
  • Inherited methods
  • getOptionData()
  • getSavedState()
  • isValidState()
  • options()
  • restoreDataFromOption()
  • setSavedState()
  • sVars()
  • updateOptionData()
• Instance properties
  • Inherited properties
• Component attributes
  • Inherited attributes

Introduction

Data Selector Input state variables are a Selector Input state variable type that contains a set of state variable data with each option.

When a new option is selected by changing the state variable's value, the saved state associated with the new selection is restored.

The default component is the same as the Selector Input state variable. However, this is usually used in conjunction with a ListPage Component, which is rendered as a scrollable and editable list with a separate area from data entry that contains state variables. When a list item is selected, it restores that item's saved state variable state.

Item state

When a Data Selector Input is saved, the state variable value, the options, and the state variable data associated with each option are saved. The app code is expected to upgrade the saved state should the options or the set of associated state variables change when a new app version is started.

Data Selector Input state variables expect the associated page to determine when the current database entry which be updated when any of the associated state variables change. For example, it can happen immediately after the user changes any associated state variable or after the user hits a "Submit" button (or equivalent). The page is expected to call the updateOptionData() method whenever it's time to update the state variable state for the currently selected option.

In addition, the page must set up the list of state variables that are associated with each option by calling the sVars() method. Typically, this is done in the page's init() method.

Adding and deleting items

The save state variable data tracks the selector options. When the option list is changed by calling the options() method, the new list is scanned, any state variable data associated with options having the same value will be preserved allowing the displayed text to change. The state variable data for newly added option values is filled in from current values.

Child state variables

• Selector child state variables

Constructor

• Type string: 'dataSelectorInput', class: DataSelectorInputSv

Syntax

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

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.
• Selector Input info properties.
• sVars (optional)
  An array of state variables and/or state variable IDs for the state variables that will be saved for each list item.

Instance methods

Inherited methods

• StateVar methods
• ModelValueSv methods
• InputSv methods
• Selector Input methods.

Note: The component() method returns a SelectorInputSvCmp.

getOptionData()

Syntax

getOptionData(value)
getOptionData()

Returns an object containing the saved data associated with the option that contains value. If value is omitted, the current dataSelectorInput value is used. The returned object is the same as returned by SV.getSavedState() for the list of saved state variables.

Return value

An object with a property corresponding to the ID of each state variable. The property value is the state variable value.

getSavedState()

Syntax

getSavedState()

Return an object containing the current state of the dataSelectorInput state variable, including the value, and the value, text, and the associated state variable data for each option.

Return value

An object containing the following properties:

• value
  Any type. The selected option value.
• options
  An array of options. Each element is an object containing the following properties:
  • text
    The text to display for the option.
  • value

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

  • data

    The data associated with the option. An object with a property corresponding to the ID of each saved state variable. The property value is the state variable value.
  

isValidState()

Syntax

isValidState(state)

Returns true if state is valid for providing to the [setSavedState() method]. Checks that:

• state is a plain Object.
• The state object contains a value and an option array.
• The options list contains the value.
• The state variable data associated with each option contains valid state variable IDs.

Return value

A Boolean.

options()

Syntax

options(opts, value)
options(opts)

Sets the state variable options according to the array of options 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 dflt parameter is not present in the updated options, then it is set to value if that value is present in the options or to the first option value if not present.

Parameters

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

• 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.
• data
  The data associated with the option. An object with a property corresponding to the ID of each saved state variable. The property value is the state variable value.

restoreDataFromOption()

Syntax

restoreDataFromOption()

Restore the state variable values from the data associated with the currently selected option.

setSavedState()

Syntax

setSavedState(state)

Restore the state variable state from state. state is an object returned by the getSavedState() method. The following state is resored:

• The current state variable value.
• The list of options. For each option, the setSavedState()method will restore the option value, the option text, and the state variable data saved from the last time the option was created or updated.
  The list of state variables to be saved is not restored. It is expected that the page the owns the dataSelectorInput will set that up using hte sVars() method before calling the updateOptionData() method.

Parameters

• state
  An object containing the following properties or previously obtained from the getSavedState() method:
  • value
    Any type. The selected option value.
  • options
    An array of options. Each element is an object containing the following properties:
    • text
      The text to display for the option.
    • value

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

    • data

      The data associated with the option. An object with a property corresponding to the ID of each saved state variable. The property value is the state variable value.
    

sVars()

Syntax

sVars(...)
sVars()

If any arguments are present, it sets the list of state variables to saved with each option. This does not affect the previously saved in the current options list. If no arguments are provided it returns an array of the current associated state variables that will be captured when the updateOptionData() method is called.

The sVars() method returns the current array of state variables to be saved with each option.

Parameters

Each parameter specifies a single matching criteria. The meaning of each parameter depends on its type:

• StateVar
  Adds the state variable to the returned array.
• String
  Adds the state variable that has the same ID string to the returned array.
• RegExp
  Add state variables with IDs that match the RegExp to the returned array.
• Function
  All state variables for which calling the function with the state variable as an argument returns true are added to the returned array.
• Array
  An array of criteria. Add the state variables that match any of the criteria.

Return value

An array containing StateVar objects.

updateOptionData()

Syntax

updateOptionData(value)
updateOptionData()

If value is omitted, updateOptionData() updates the data associated with the currently selected option from the current value of the state variables in the list of state variables to be saved. If value is provided it updates the data associated with the option specified by value, if present in the option list.

Instance properties

Inherited properties

• StateVar properties
• ModelValueSv properties
• InputSv properties
• Selector Input properties.

Component attributes

Inherited attributes

• Component attributes
• Selector attributes