Class: module:br/presenter/node/MultiSelectionField

module:br/presenter/node/MultiSelectionField

A PresentationNode containing all of the attributes necessary to model a multi-selection field on screen.

Multi-Selection fields can be rendered using a number of different controls:

  • check boxes
  • multi select box

By default, multi-selection fields are automatically configured to update the currently selected options (held within #value) if the list of available #options changes — any selected options that are no longer available will be automatically removed from the list. You can change this behaviour by invoking #automaticallyUpdateValueWhenOptionsChange with false.

Constructor

new module:br/presenter/node/MultiSelectionField(vOptions, vValues)

Extends:
Parameters:
Name Type Description
vOptions Object The list of available options, either using an array, a map of strings or as a module:br/presenter/node/OptionsNodeList.
vValues Object (optional) The list of currently selected options, either using an array or as a module:br/presenter/property/EditableProperty containing an array.
Source:

Extends

Members

controlName :br.presenter.property.WritableProperty

The logical control-name the multi-selection field is being bound to — this value will appear within the name attribute if being bound to a native HTML control.
Type:
  • br.presenter.property.WritableProperty
Source:

enabled :br.presenter.property.WritableProperty

A boolean property representing whether the multi-selection field is enabled or not.
Type:
  • br.presenter.property.WritableProperty
Source:

failureMessage :br.presenter.property.WritableProperty

A textual description of the currently failing validation message when #hasError is true.
Type:
  • br.presenter.property.WritableProperty
Source:

hasError :br.presenter.property.WritableProperty

A boolean property that is true if #value has any validation errors, and false otherwise.
Type:
  • br.presenter.property.WritableProperty
Source:

label :br.presenter.property.WritableProperty

The textual label associated with the multi-selection field.
Type:
  • br.presenter.property.WritableProperty
Source:

options :br.presenter.node.OptionsNodeList

The current list of options the user can select from.
Type:
  • br.presenter.node.OptionsNodeList
Source:

value :br.presenter.property.WritableProperty

The list of currently selected options.
Type:
  • br.presenter.property.WritableProperty
Source:

visible :br.presenter.property.WritableProperty

A boolean property representing whether the multi-selection field is visible or not.
Type:
  • br.presenter.property.WritableProperty
Source:

Methods

allowInvalidSelections(bAllowInvalidSelections)

Whether the multi-selection field displays a validation error if the selected values (within #value) contain items that are not members of the #options array.

Invalid selections cause validation errors by default, but this rarely happens with multi-selection fields since #value automatically updates if the underlying #options change by default, and standard multi-selection controls don't allow unconstrained user input.

Parameters:
Name Type Description
bAllowInvalidSelections boolean Invalid selections are allowed when set to true.
Source:

automaticallyUpdateValueWhenOptionsChange(bAutomaticallyUpdate)

Whether the selection field automatically picks a new #value when the underlying #options change.

If the underlying #options change, so that #value still refers to options that no longer exist, a validation error would be displayed if it were not for the fact that invalid selections are automatically removed by default when this happens. Automatically updating the #value may not be desirable in all cases, and it may preferable instead to display a validation error so the user can be made fully aware that their selection requires change.

Parameters:
Name Type Description
bAutomaticallyUpdate boolean True to automatically update values
Source:
See:

getPath()

Returns the path that would be required to bind this node from the view.

This method is used internally, but might also be useful in allowing the dynamic construction of views for arbitrary presentation models.

Inherited From:
Source:

nodes(sNodeName, vProperties)

Returns all nested nodes matching the search criteria reachable from this node.

Care is taken not to search up the tree in cyclic presentation models (where some of the presentation nodes have back references to presentation nodes higher up in the tree).

Parameters:
Name Type Description
sNodeName String The name of nodes to match.
vProperties Object Only nodes having this array or map of properties will be matched.
Inherited From:
Source:
See:

properties(sPropertyName, vValue)

Returns all nested properties matching the search criteria reachable from this node.

Care is taken not to search up the tree in cyclic presentation models (where some of the presentation nodes have back references to presentation nodes higher up in the tree).

Parameters:
Name Type Description
sPropertyName String The name of properties to match.
vValue Object The value of properties to match.
Inherited From:
Source:
See:

removeAllListeners()

Inherited From:
Deprecated:
  • This method has been replaced by #removeChildListeners which recurses the node tree. Removes all listeners attached to the properties contained by this PresentationNode.
    Source:

    removeChildListeners()

    Removes all listeners attached to the properties contained by this PresentationNode, and any nodes it contains.
    Inherited From:
    Source: