Module bauplan.control.view

Control component view

var ControlView = require("bauplan.control.view");

Provides default control views and methods to register additional control types, formats and primitives

Any control for an attribute that is registered as having any of these kinds will have that kind’s phase methods executed automatically when the corresponding phase runs

Kinds

Primitives represent native JSON schema types that can be assigned to a model’s attribute, eg. string, boolean, integer

Formats represent format types that can be assigned to a model’s attribute

Control types represent a spcecialised control that that can be assigned to a model’s attribute

Phase methods

All kinds can provide any of the following phase methods as needed

  • prepare - does any extra work required to get the value during the control’s initialisation
  • format - formats the value to be displayed

  • normalize - ensures that value is in the right format

    eg. collates data if in several input fields or transforms a date string in to an actual date object

  • validate - validates the normalized value, adding any errors encountered to an error stack

NB. It is preferable to use the control.view template template rather than make a new ControlView directly

Returns

ControlView

Type
constructor

Extends

  • Thorax.View

Requires

Source:

Members

(private, inner) controlError :boolean

Whether the control has an error

Type:
  • boolean
Source:

(private, inner) controlErrorFlag :boolean

Whether the control should display an error

Type:
  • boolean
Source:

(inner) controltypes :object

Control type kind register

Type:
  • object
Source:

(private, inner) errorDisplayStack :array

Array of errors for control

Type:
  • array
Source:

(inner) events

Source:
To Do:

  • EVENTS

(inner) formats :object

Format kind register

Type:
  • object
Source:

(inner) kinds :array

List of control kinds

Type:
  • array
Source:

(inner) name :string

View name

Type:
  • string
Default Value:
  • control
Source:

(inner) primitives :object

Primitive kind register

Type:
  • object
Source:

(inner) template :string

Template key

Type:
  • string
Default Value:
  • control.view
Source:

(inner) valueAttribute :string

Control property to use to obtain controls’s value

Type:
  • string
Default Value:
  • value
Source:

Methods

(static) addControlType(attrs)

Allows additonal controls to add controltypes

Parameters
Name Type Description
attrs object
Source:

(static) addFormat(attrs)

Allows additonal controls to add formats

Parameters
Name Type Description
attrs object
Source:

(static) addNormalization(attrs)

Allows additonal controls to add normalization methods

Parameters
Name Type Description
attrs object
Source:

(static) addPreparation(attrs)

Allows additonal controls to add preparation methods

Parameters
Name Type Description
attrs object
Source:

(static) addPrimitive(attrs)

Allows additonal controls to add primitives

Parameters
Name Type Description
attrs object
Source:

(static) addValidation(attrs)

Allows additonal controls to add validation methods

Parameters
Name Type Description
attrs object
Source:

(static) extend(valueAttributeopt) → {constructor}

Parameters
Name Type Attributes Default Description
valueAttribute string <optional>
 value

Control property to use to obtain controls’s value
Source:
Returns

ControlView

Type
constructor

(inner) addError(err, options)

Sets this.controlError to true If the error is to be displayed also sets this.controlErrorFlag and adds the error to this.errorDisplayStack using the method specified (push by default)

Parameters
Name Type Attributes Default Description
err string

Error name (can be a phrasekey)
options object

Following options
options.​display boolean <optional>
 false

Whether to display error
options.​forceDisplay boolean <optional>
 false

Whether to force display
options.​method string <optional>
 push

Method to use to add error to stack
Source:

(private, inner) addMethod(attrs)

Attaches method of right kind to control

Parameters
Name Type Description
attrs object
Source:

(private, inner) addTypeMethods(attrs)

Generic handler to allow additonal controls to add kinds methods

Checks the existence of the following methods and, if found, adds it to the control

  • initialize
  • prepare
  • normalize
  • validate
Parameters
Name Type Description
attrs object
Source:

(inner) context() → {object}

Deletes attributes meant for label and not for control input

Assigns template to text.{{mode}} if controltype does not have a template

Overrides Thorax.View.prototype.context

Source:
Returns

View attributes

Type
object

(inner) displayErrors(value)

Looks up and computes error templates

Checks in turn for the a i18n phrase for the keys and uses the first non-empty value

  1. {{phrasekey}}.error.{{error}} (as key for phrase lookup)
  2. control.error.{{error}} (as key for phrase lookup)
  3. {{error}} (as is)

eg. if there was an oops error on the bar property of the foo model

  1. model.foo.bar.error.oops
  2. control.error.oops
  3. "oops"

The control's name, label and value are passed to Larynx Phrase where they can be used for substitution purposes

Parameters
Name Type Description
value string

Control's value
Source:

(private, inner) flagError(hasErroropt)

Toggles control-error class on control view element

Parameters
Name Type Attributes Default Description
hasError boolean <optional>
 false

Whether to show an error. Forced to true if this.controlErrorFlag
Source:

(private, inner) getDisplayErrors() → {array}

Source:
Returns

List of errors to be displayed for the control

Type
array

(inner) getError() → {boolean}

Source:
Returns

Whether control has an error

Type
boolean

(inner) getValue() → {*}

Returns control value irrespective of control type

Source:
Returns

The control's current value

Type
*

(inner) initialize(options)

  • Determines whether mode is edit or display
    • if schema property has fixed, then the control is uneditable and mode will always be display
  • Sets empty controlmodel if none passed
  • Sets dirty model
  • Removes any property prefixed with control-
  • Adds relevant initialization methods
  • Applies relevant prepare methods
  • Attaches schema
  • Creates clean model for control
  • Create messages model for control
  • Update model
Parameters
Name Type Description
options object

Options

Properties
Name Type Attributes Default Description
control-name string

The name to use for the control inoput’s name (or equivalent)
edit string <optional>
 true

Edit mode - whether to render an editable or display version of the control view
display string <optional>
 false

Inverse alias for edit. NB. has no effect if edit is defined
model object <optional>

Model to bind to the control (controlmodel). Can also be passed as control-model. If not passed, a new empty Thorax Model is used.
instant-validate boolean <optional>

Whether to perform instant validation on the control
required boolean <optional>
 false

Whether the control is required to have a value
multiline boolean <optional>
 false

Whether a text input is allowed to have multiple lines
value string <optional>

The initial value for the control. If not provided the control will retrieve the value from the control model using the control's name (control-name) as the property
control-id string <optional>

Value to use for control’s id. If not provided the control will use control-{{controlname}}
phrasekey string <optional>

Phrasekey to use for control.

If not provided the control will attempt to use

  • {{controlmodel._phrasekey}}
  • model.{{controlmodel._model}}.{{controlname}}
label string <optional>

Text for control’s label.

If not provided the control will attempt to use {{phrasekey}}.label as a lookup key, falling back to using the controlname if none is found
placeholder string <optional>

Text to use for placeholder

If not provided the control will attempt to use {{phrasekey}}.placeholder
note string <optional>

Text for control’s note.

If not provided the control will attempt to use {{phrasekey}}.note
control-keyup boolean <optional>
 false

Whether to validate on keyup
control-type string <optional>

Overrides any controltype that may have been specified by the controlmodel’s schema
control-primitive string <optional>

Overrides any primitive that may have been specified by the controlmodel’s schema
control-format string <optional>

Overrides any format that may have been specified by the controlmodel’s schema
parent viewmodel <optional>

The parent view this control should belong to
Source:

(private, inner) instantValidateControl(value, optionsopt)

Calls validation on a control immediately and updates parent view

Parameters
Name Type Attributes Description
value *

Control's value
options object <optional>

Validation options
Source:

(private, inner) normalizeControl(value) → {*}

Calls bauplan.control.view~normalizePrimitive, bauplan.control.view~normalizeFormat, bauplan.control.view~normalizeControlType

Parameters
Name Type Description
value *

Control value
Source:
Returns

Updated value

Type
*

(private, inner) normalizeControlType(value) → {*}

Passes params to bauplan.control.view~normalizeMethod

Parameters
Name Type Description
value *

Control value
Source:
Returns

Updated value

Type
*

(private, inner) normalizeFormat(value) → {*}

Passes params to bauplan.control.view~normalizeMethod

Parameters
Name Type Description
value *

Control value
Source:
Returns

Updated value

Type
*

(private, inner) normalizeMethod(value, kind) → {*}

Generic normalize method handler for kinds. Passes params to bauplan.control.view~registeredMethod

Parameters
Name Type Description
value *

Control value
kind string

Name of kind
Source:
Returns

Updated value

Type
*

(private, inner) normalizePrimitive(value) → {*}

Passes params to bauplan.control.view~normalizeMethod

Parameters
Name Type Description
value *

Control value
Source:
Returns

Updated value

Type
*

(private, inner) prepareControl(control, phrasekeyopt, options) → {control}

Passes params to bauplan.control.view~prepareMethod

Parameters
Name Type Attributes Description
control control

Control view object
phrasekey string <optional>

Optional phrasekey for lookups
options object

Additional options
Source:
Returns

Updated control

Type
control

(private, inner) prepareFormat(control, phrasekeyopt, options) → {control}

Passes params to bauplan.control.view~prepareMethod

Parameters
Name Type Attributes Description
control control

Control view object
phrasekey string <optional>

Optional phrasekey for lookups
options object

Additional options
Source:
Returns

Updated control

Type
control

(private, inner) prepareMethod(kind, control, phrasekeyopt, options) → {control}

Generic handler for applying kinds prepare methods to control

Parameters
Name Type Attributes Description
kind string

Name of kind
control control

Control view object
phrasekey string <optional>

Optional phrasekey for lookups
options object

Additional options
Source:
Returns

Updated control

Type
control

(private, inner) preparePrimitive(control, phrasekeyopt, options) → {control}

Passes params to bauplan.control.view~prepareMethod

Parameters
Name Type Attributes Description
control control

Control view object
phrasekey string <optional>

Optional phrasekey for lookups
options object

Additional options
Source:
Returns

Updated control

Type
control

(private, inner) registeredMethod(value, kind, control, options) → {control}

Generic handler for applying kinds methods to control

Parameters
Name Type Description
value *

Control value
kind string

Name of kind
control control

Control view object
options object

Additional options
Source:
Returns

Updated control

Type
control

(private, inner) startErrorReport()

Notes the existence of any previous errors and resets this.controlError, this.controlErrorFlag and this.errorDisplayStack

Source:

(inner) updateControl(value, options)

Validate the control Display errors (if any) If no error

  • update model silently
  • update control model if changed (silently if the option is set)
Parameters
Name Type Description
value *

Control value. If passed as an object, will get the value using this.getValue() and set options to value’s value
options object

Update options
Source:

(private, inner) updateParent(optionsopt)

If the control has a parent view

  • disable parent view form if it has an error
  • revalidate all parent view controls if the control previously had an error
Parameters
Name Type Attributes Description
options object <optional>

Options

Properties
Name Type Attributes Description
norevalidation boolean <optional>

Whether to prevent revalidation
Source:

(private, inner) validateControl(value, options) → {*}

Does nothing if in display mode

  • Clears previous errors
  • Trims string values
  • Normalizes value
  • Adds error explicitly passed in options
  • Calls
    • this.validateRequired
    • this.validatePrimitive
    • this.validateFormat
    • this.validateControlType
  • call flagError if appropriate
  • silently sets dirtymodel
  • silently sets controldirtymodel (if there is one)
  • if value has changed, sets controlparent's initialValues to false
  • updates parent view if appropriate
Parameters
Name Type Attributes Default Description
value *

Control value
options object

Additional validation options
options.​error string <optional>

Manually passed error name/phrasekey
options.​rendered boolean <optional>
 true

Whether to flag up any error
options.​forceDisplay boolean <optional>
 true

Whether to force the display of any error
options.​norevalidation boolean <optional>
 false

Whether to trigger revalidation of all the parent view's controls
Source:
Returns

Updated value

Type
*

(private, inner) validateControlType(value, options) → {errorModel}

Generic validation method for kinds. Passes params to bauplan.control.view~validateMethod

Parameters
Name Type Description
value *

Control value
options object

Additional validation options
Source:
Returns

messages

Type
errorModel

(private, inner) validateFormat(value, options) → {errorModel}

Generic validation method for kinds. Passes params to bauplan.control.view~validateMethod

Parameters
Name Type Description
value *

Control value
options object

Additional validation options
Source:
Returns

messages

Type
errorModel

(private, inner) validateMethod(value, kind, options) → {errorModel}

Generic validation method for kinds. Passes params to bauplan.control.view~registeredMethod

Parameters
Name Type Description
value *

Control value
kind string

Name of kind
options object

Additional validation options
Source:
Returns

messages

Type
errorModel

(private, inner) validatePrimitive(value, options) → {errorModel}

Generic validation method for kinds. Passes params to bauplan.control.view~validateMethod

Parameters
Name Type Description
value *

Control value
options object

Additional validation options
Source:
Returns

messages

Type
errorModel

(inner) validateRequired(value, options) → {boolean}

Returns whether or not a control has a value

If the field is required the following values are treated as absent

  • undefined
  • empty string
  • false if primitive is boolean
  • null if primitive is not null

If the value is absent and the control is required, a required error is added to the control unless

  • the control model either had no previous value for the property
  • options.forecDisplay is true

Id the field is not required, absent is calculated based on the truthiness of the value

Parameters
Name Type Description
value *

Control value
options object

Additonal validation options
Source:
Returns

absent Whether control has no value

Type
boolean