Data Selector Input state variables are an Input SV type (class DataSelectorInputSv extends InputSv) that behave like a Selector Input and contain a set of state variable data with each option. They are not a subclass of SelectorInputSv: the option-handling methods (options(), findOption(), hasOption(), optionValues(), optionTexts(), text, fmtVal(), and isValid()) are reimplemented here and differ from the Selector Input versions in the ways noted below. There is no isStatic property; the options can always be changed.
When a new option is selected by changing the state variable's value, the saved state associated with the new selection is restored. This happens in val(): when the options exist and the new value differs from the current value, the value (undefined means the first option) must be one of the options (otherwise an assertion fails), and the option's data is restored to the associated state variables.
'' optionThe value '' is reserved for a "nothing selected" option. It may appear only as the first option, and its data is always {}. It is excluded from optionValues() and optionTexts(), and findOption() and getOptionData() never match it. Setting the value to '' does not restore any data.
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.
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.
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 (the current state of the state variables listed by sVars()).
'dataSelectorInput', class: DataSelectorInputSvctl.createPage({
...,
stateVarInfo:[
{type:'dataSelectorInput', ...},
],
})
infoinfo object can contain the following properties, but subclasses of StateVar may have additional properties:info properties.info properties.info properties.options is not read from info. Set the options by calling options() after construction.sVars is not read from info. Set the associated state variables by calling the sVars() method.Note: The component() method returns a SelectorInputSvCmp, the same component as a Selector Input.
findOption()findOption(value)
findOption()
Returns the option object with value (default: the current value), or undefined if there is none. Always returns undefined for '' or undefined.
hasOption()hasOption(value)
Returns true if an option with value exists (including the reserved '' option).
optionValues()Returns an array of the option values, excluding the reserved '' option.
optionTexts()Returns an array of the option texts, excluding the reserved '' option.
fmtVal()Returns the displayed text for the current value (the text property), or '' if no option matches.
isValid()isValid(value)
Returns true if there are no options yet, or if value (default: the current value) is one of the options.
setDflt()setDflt()
Clears the options (options([])) and calls setDflt() on each of the associated state variables from sVars().
optionDataChanged()optionDataChanged()
Signals that stored option data was modified in place (for example, by mutating the object returned by getOptionData()), so that the change is saved.
getOptionData()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.
An object with a property corresponding to the ID of each state variable. The property value is the state variable value. Returns null if there is no option with value. If the returned object is modified in place, call optionDataChanged().
getSavedState()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.
An object containing the following properties:
valueoptionstextvalue 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()isValidState(state)
Returns true if state is valid for providing to the [setSavedState() method]. Checks that:
state is a plain Object.state.options is an array. Each option is a plain Object with a value, a string text, and a plain Object data.undefined, null, '', or one of the option values (unless there are no options).'' value appears only in the first option.A Boolean.
options()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, and if dflt is not among the options it is set to value.
If value is not present, then if dflt is not among the updated options it is set to the first option value, and the state variable value is then always set to dflt (which restores that option's data).
If opts is empty, the options are cleared, dflt becomes undefined, and the value is set to undefined.
Data already associated with an existing option value is preserved; new values get data captured from the current associated state variables, and '' gets {}.
optstext (optional)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)dflt (see above).An array of option objects, each containing the following properties:
textvaluedatarestoreDataFromOption()restoreDataFromOption()
Restore the state variable values from the data associated with the currently selected option.
setSavedState()setSavedState(state)
Restore the state variable state from state. state is an object returned by the getSavedState() method. The following state is resored:
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.state is not valid (see isValidState()), the options are cleared and the value is set to undefined. 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.stategetSavedState() method:valueoptionstextvalue 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()sVars(...)
sVars()
If any arguments are present, it sets the list of state variables to saved with each option. For unit state variables, the data is captured from the current unit sibling. 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.
Each parameter specifies a single matching criteria. The meaning of each parameter depends on its type:
An array containing StateVar objects.
updateOptionData()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.
isSelectorAlways true for dataSelectorInput.
A Boolean.
text (read only)The option text associated with the current state variable value, or '' if none.
A String.