Home | Class Index

SDK Version: 3.11.4-302512

Documentation generated on 24 July 2015

Class
caplin.presenter.node

MultiSelectionField

Extends caplin.presenter.node.PresentationNode.
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 Summary

Attributes Name and Description
caplin.presenter.node.MultiSelectionField(Object vOptions, Object vValues)

Constructs a new instance of SelectionField.

Field Summary

Attributes Name and Description
controlName

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.
enabled

A boolean property representing whether the multi-selection field is enabled or not.
failureMessage

A textual description of the currently failing validation message when #hasError is true.
hasError

A boolean property that is true if #value has any validation errors, and false otherwise.
label

The textual label associated with the multi-selection field.
options

The current list of options the user can select from.
value

The list of currently selected options.
visible

A boolean property representing whether the multi-selection field is visible or not.

Method Summary

Attributes Name and Description
void allowInvalidSelections(boolean 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.
void automaticallyUpdateValueWhenOptionsChange(boolean bAutomaticallyUpdate)

Whether the selection field automatically picks a new #value when the underlying #options change.
Methods inherited from class caplin.presenter.node.PresentationNode:
getPath, nodes, properties, removeAllListeners, removeChildListeners

Constructor Detail

► caplin.presenter.node.MultiSelectionField(Object vOptions, Object vValues)

Constructs a new instance of SelectionField.

Parameters
Object vOptions The list of available options, either using an array, a map of strings or as a caplin.presenter.node.OptionsNodeList.
Object vValues (optional) The list of currently selected options, either using an array or as a caplin.presenter.property.EditableProperty containing an array.

Field Detail

► caplin.presenter.property.WritableProperty controlName

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.

► caplin.presenter.property.WritableProperty enabled

A boolean property representing whether the multi-selection field is enabled or not.

► caplin.presenter.property.WritableProperty failureMessage

A textual description of the currently failing validation message when #hasError is true.

► caplin.presenter.property.WritableProperty hasError

A boolean property that is true if #value has any validation errors, and false otherwise.

► caplin.presenter.property.WritableProperty label

The textual label associated with the multi-selection field.

► caplin.presenter.node.OptionsNodeList options

The current list of options the user can select from.

► caplin.presenter.property.WritableProperty value

The list of currently selected options.

► caplin.presenter.property.WritableProperty visible

A boolean property representing whether the multi-selection field is visible or not.

Method Detail

► void allowInvalidSelections(boolean 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
boolean bAllowInvalidSelections Invalid selections are allowed when set to true.

► void automaticallyUpdateValueWhenOptionsChange(boolean 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
boolean bAutomaticallyUpdate True to automatically update values
See
#allowInvalidSelections