SV (stateVar) Object Reference

Related documents

• State Variables Overview
• StateVar Reference
• Built-in State Variables

Table of contents

• Introduction
• Methods
  • SV.addHistory()
  • SV.all()
  • SV.allIds()
  • SV.create()
  • SV.defineType()
  • SV.find()
  • SV.getHistory()
  • SV.getSavedState()
  • SV.getSv()
  • SV.getTypeClass()
  • SV.isStateVar()
  • SV.isSvError()
  • SV.isValid()
  • SV.namespace()
  • SV.parseId()
  • SV.setSavedState()
  • SV.toIds()
  • SV.toPageIds()

Introduction

The stateVar or SV object provides methods for controlling all state variables. SV is an alias for the stateVar object. Both SV and stateVar are properties of the window object and do not have to be imported.

Methods

SV.addHistory()

Syntax

SV.addHistory(id, value)

Adds a state variable ID and value to the global state variable history. The StateVar superclass automatically does this when a changed value is assigned to a state variable marked for saving (usually a user input). SV types that override the assignment method without calling the superclass will need to call this themselves.

Parameters

• id
  A state variable ID.
• value
  The state variable value to add to the history.

SV.all()

Syntax

SV.all()

Returns an array containing all public state variables.

Return value

An array of state variables.

SV.allIds()

Syntax

SV.allIds()

Returns an array containing the IDs of all public state variables.

Return value

An array of state variable ID strings.

SV.create()

Syntax

SV.create(info)

Creates a new public state variable. The ID in info.id is published in the global sv namespace, and is searchable by the find() method. The SV type in info.type can be a string defined by the defineType() method or a class.

Non-public state variables can be created using the state variable class constructor.

Parameters

• info
  An object containing the properties required for the SV type. info must contain:

  • id
    The state variable ID string
  • type
    An SV type string or StateVar subclass that specifies the SV type to be created.

  info may also contain these properties from the StateVar superclass, in addition to properties unique to the subclass:

  • value
    The state variable’s initial value. The JS type of the value is dependent on the SV type.

  • save
    The save property may take one of the following values:

    • 'global'
      Save the state variable state both locally and to the cloud. This is the default value for Input-type state variables.
    • 'local'
      Save the state variable state both locally and to the cloud. When cloud values are used to restore state variable state, the locally saved values
      override the cloud values.
    • 'local'
      Don't save the state variable state. This is the default value for Output-type state variables.

  • onError
    A function to be called when an invalid value is assigned.

    The function signature is fn(sVar, newValue):

    • sVar
      The current state variable.
    • newValue
      The proposed new value for the state variable.

Return value

A new state variable.

SV.defineType()

Syntax

SV.defineType(typeName, typeClass)

Associates the String typeName with the class typeClass. The string can be used to as the SV type to create a new state variable.

Parameters

• typeName
  A string that will identify the class. It must be unique to all published SV types.
• typeClass
  The SV type's class. It must be a subclass of StateVar.

SV.find()

Syntax

SV.find(...)

Find all public state variables meeting the criteria expressed in the arguments and return them in an array. If more than one argument is present, then state variables that meet any of the criteria are returned.

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.

For example,

SV.find(sVar => (sVar.page === myPage && sVar.isInput))

will return an array of all Model Input state variables associated with myPage.

SV.getHistory()

Syntax

SV.getHistory(count)

Return an array of the last count entries of state variable history ordered from oldest to newest. Each entry is an array with the state variable ID as the first element and the value as the second. This method is useful for debugging and is also used by the Controller to save some amount of history with the saved state.

Parameters

• count
  The number of history elements to return.

Return value

An array of history elements, each with the state variable ID as the first element and the value as the second.

SV.getSavedState()

Syntax

SV.getSavedState(sVars)

Return an object containing the saved state of the state variables in the array passed as an argument. For each state variable, the returned object has a property that is the state variable ID with a value that represents the saved state variable state. The value may be a primitive type or an object, depending on the SV type.

Parameters

• sVars
  An array of state variables.

Return value

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

SV.getSv()

Syntax

SV.getSv(idOrSv)

Get a StateVar object. If idOrSv is already a StateVar object, it is returned. If idOrSv is a valid state variable ID then the associated StateVar object is returned. Otherwise, getSv() produces an assertion failure.

Parameters

• idOrSv
  A string or StateVar.

Return value

A StateVar object.

SV.getTypeClass()

Syntax

SV.getTypeClass(typeName)

Return the state variable class associated with typeName.

Parameters

• typeName
  A string.

Return value

The StateVar class or a subclass of StateVar.

SV.isStateVar()

Syntax

SV.isStateVar(arg)

Returns true if arg is a state variable (an instance of StateVar) or an ID string for an existing state variable.

Parameters

• arg
  A value to be tested.

Return value

A Boolean. True if arg corresponds to a state variable.

SV.isSvError()

Syntax

SV.isSvError(arg)

Returns true if arg is an instance of StateVarError.

Parameters

• arg
  A value to be tested.

Return value

A Boolean. True if arg is an instance of StateVarError.

SV.isValid()

Syntax

SV.isValid(...)

Return true if all arguments are valid. Arguments that are undefined, NaN, or instances of StateVarError objects are invalid. If an argument is a state variable ID string or a state variable object, it's valid if the associated state variable is valid.

Parameters

Each parameter is a value to be tested for validity.

Return value

A Boolean. True if all arguments are valid values or are state variables that have valid values.

SV.namespace()

Syntax

SV.namespace(...)

Return an object containing a property that is the ID for each state variable meeting the criteria expressed in the arguments (same as find()). The associated value is the state variable object. If more than one argument is present, then state variables that meet any of the criteria are included. The returned object is frozen and cannot be modified.

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 object.
• String
  Adds the state variable that has the same ID string to the returned object.
• RegExp
  Add state variables with IDs that match the RegExp to the returned object.
• Function
  A function with the signature: fn(sVar). All state variables for which calling the function with the state variable as the sVar argument returns true are added to the returned object.
• Array
  An array of criteria. Add the state variables that match any of the criteria to the returned object.

Return value

A frozen object containing properties for all state variables meeting any of the criteria. The property name is the state variable ID, and the property value is the state variable object.

SV.parseId()

Syntax

SV.parseId(id)

Returns an object with the following properties:

• page
  The page part of the id.
• name
  The name part of the id.
• subNames
  An array of sub-names.

The ID must be of the form '<page>_<name>', '<page>_<name>_<subName>', or '<page>_<name>_<subName>_<subName>...'

Parameters

A state variable ID string.

Return value

An object.

SV.setSavedState()

Syntax

SV.setSavedState(state)

Restore the state of state variables from the state object. The state object is the same as the one returned by getSavedState(). For each enumerable property in state, the the key is used to find the associated state variable object, and then the state variable's setSavedState() method is called with the property value. The value may be a primitive type or an object depending on the SV type.

Parameters

• state
  An object is retrieved by the getSavedState() method.

SV.toIds()

Syntax

SV.toIds(SVars)

Returns an array of IDs corresponding to the state variables in the sVars array.

Parameters

• sVars
  An array of state variables.

Return value

Returns an array of state variable ID strings.

SV.toPageIds()

Syntax

SV.toPageIds(SVars)

Returns a deduplicated array of the page properties from the state variables in the sVars array.

Parameters

• sVars
  An array of state variables.

Return value

Returns an array of page ID strings.