Input SV Type Reference

Related documents

• State Variables Overview
• StateVar Reference
• Built-in State Variables
• Model SV Type Reference
• Output SV Type Reference

Table of contents

• Introduction
  • onUserChange() handler
• Constructor
• Instance methods
  • Inherited methods
  • fmtVal()
  • getSavedState()
  • setSavedState()
  • userChange()
• Instance properties
  • Inherited properties
  • className
  • dflt
  • isDisabled
• Component
• Component attributes
  • Inherited attributes
  • sVar
  • valueOnly
• Component methods
  • setDisabled()
  • setValue()
  • sync()
• Component properties
  • sVar
  • _mon.sVar
  • _mon.isDisabled
• Standard DOM element properties

Introduction

Input SV types inherit from the Model SV type (type:'modelValue', class:ModelValueSv). The class is InputSv. The InputSv class is intended to be the superclass for user inputs. It is not intended for direct use and has no published type string.

Instances of Input SV types will have the isInput property set to true.
The isDisabled property is supported.

onUserChange() handler

Input SV types can specify an onUserChange() handler that will be called whenever the user changes the input to accept, reject, or modify the user input. When called, the handler should set the state variable value to the new or modified value. The new value will be reflected in the user-visible input field. If the state variable value is not changed, then the old state variable value is restored to the input field.

Constructor

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.
  • onUserChange
    The value is a function that will be called whenever the user changes the input. It will not be called when state variables are restored on startup or when internal code changes the input. This gives the function the option of accepting, rejecting, or modifying the user input.

The function has the following signature: fn(sVar, newValue). The sVar argument is the changed state variable, and the newValue is the value the user has just entered. The function can set the state variable to the new value, modify the value before setting the state variable, or take some other action if the value is not acceptable. When the function returns, the displayed input value will be updated to the current value of the state variable.

Instance methods

Note: the default component() method will return a component that uses the state variable's render() method as its render() method.

Inherited methods

• StateVar methods
• ModelValueSv methods

fmtVal()

Syntax

fmtVal()

Return a formatted value. The format information varies with subclass.

Return value

A string representing a formatted version of the value.

getSavedState()

Syntax

getSavedState()

Returns the state variable state to be saved. The default method returns the current value of the state variable. If the saved state is more complex, override this method in subclasses.

Return value

Any JavaScrtipt type.

setSavedState()

Syntax

setSavedState(state)

Sets the state variable to the internal state specified by state. If the state is invalid, the state variable has the option to set the state to the default state.

Parameters

• state
  The state previously returned by getSavedState().

userChange()

Syntax

userChange(value)

The userChange() method should be called by the DOM node that handles user input in the node's onchange handler. The default implementation calls the state variable's isDifferent() function with the value argument. If the value is different, it does the following:

• If the state variable has a onUserChange callback function specified:
  • Calls onUserChange(sVar, value).
  • If the state variable value is not equal to value (i.e., the value set by the user) following the call to onUserChange(), it synchronizes the view to display the updated value.
• If no onUserChange callback function is specified, it sets the state variable value to the user value.

Instance properties

Inherited properties

• StateVar properties
• ModelValueSv properties

Notes:

• The isInput property is true for Input SV types.
• The default value of the save property for Input SV types is 'global', if not specified at construction.

className

A CSS class string set on all representations of this state variable in the View. Uses the className childSv.

Value

A CSS class string.

dflt

The value assigned when setDflt() is called. If dflt is not specified, then the value property is used. If neither dflt or value is specified, then dflt is dependent on the SV type.

Value

A value appropriate for the SV type.

isDisabled

Setting isDisabled to true will disable the input. The input will be displayed as greyed-out, and the user will not be able to modify it. The value is true if the input is disabled.

Value

A value appropriate for the SV type.

Component

IoComponent should be superClass for all Components for input or output state variables. The IoComponent will setup an SvMonitor for the state variable passed in the sVar attribute and synchronizes the DOM value when it changes using the setValue() method. If the sVar is an input, it will set an SvMonitor for sVar.childSv.isDisabled and synchronize the DOM node's disabled attribute using the setDisabled() method.

Component attributes

Inherited attributes

• Component attributes

sVar

The state variable (the instance, not just the ID) that is associated with this component. This attribute is automatically set by the {{...}} syntax.

valueOnly

A Boolean. If true, the component should display the sVar value as unstyled inline text. Inputs will not be user-changeable. This attribute is automatically set by the {{|...|}} syntax.

Component methods

setDisabled()

Syntax

setDisabled(isDisabled)

The default setDisabled() method first checks whether there are any child components. If so, it calls the first child component's setDisabled() method. Otherwise, it sets the disabled property of the first component DOM node to setDisabled.

Subclasses should override this method if their implementation requires a different technique to disable the DOM input node.

setValue()

Syntax

setValue(value)

The default setValue() method first checks whether there are any child components. If so, it calls the first child component's setvalue() method. Otherwise, it sets the value property of the first component DOM node to value.

Subclasses should override this method if their implementation requires a different technique to set the value.

sync()

Syntax

sync()

The sync() method synchronizes the Dom value using the setValue() method. It also synchronizes the DOM node's disabled attribute using the setDisabled() method. Lastly, it calls super.sync() to synchronize child components.

Component properties

sVar

The state variable associated with this component.

_mon.sVar

This Componennt's SvMonitor for sVar.

_mon.isDisabled

This Componennt's SvMonitor for sVar.childSv.isDisabled if sVar is and input and the components valueOnly attribute is false.

Standard DOM element properties

By convention, the subclasses of IoComponent should create create DOM elements that share some common properties.

• The element will have a className that contains 'svIo_<type>' and svId_<sVar ID> in addition to any component className attributes and classSv values.
• The element will have the data-cid attribute set to the ID of the Component. This is useful to quickly find the state of the controlling component using view.getComponentById().

Subclasses are not required to obey these conventions.