Home | Class Index

SDK Version: 3.11.4-302512

Documentation generated on 24 July 2015

Class
caplin.presenter.property

EditableProperty

Extends caplin.presenter.property.WritableProperty.
Implements caplin.core.ValidationResultListener.
EditableProperty is identical to caplin.presenter.property.WritableProperty, except that it also has the ability to be edited by users.

Because editable properties can be displayed using controls that allow unconstrained input (e.g text input boxes), #addValidator can be used to add validators that provide user feedback when invalid values are entered, and #addParser can be used to help convert user input into valid forms.

Constructor Summary

Attributes Name and Description
caplin.presenter.property.EditableProperty(Object value)

Constructs a new EditableProperty instance.

Method Summary

Attributes Name and Description
caplin.presenter.property.EditableProperty addParser(caplin.core.Parser parser, Object config)

Adds a caplin.core.Parser that will be run each time the user enters a new value.
caplin.presenter.property.PropertyListener addValidationCompleteListener(Object listener, String methodName, boolean notifyImmediately)

A convenience method that allows validation complete listeners to be added for objects that do not themselves implement caplin.presenter.property.PropertyListener.
caplin.presenter.property.PropertyListener addValidationErrorListener(Object listener, String methodName, boolean notifyImmediately)

A convenience method that allows validation error listeners to be added for objects that do not themselves implement caplin.presenter.property.PropertyListener.
caplin.presenter.property.PropertyListener addValidationSuccessListener(Object listener, String methodName, boolean notifyImmediately)

A convenience method that allows validation success listeners to be added for objects that do not themselves implement caplin.presenter.property.PropertyListener.
caplin.presenter.property.EditableProperty addValidator(caplin.core.Validator validator, Object config)

Adds a caplin.core.Validator that will be run each time the user enters a new value.
void forceValidation()

Force the property to be re-validated.
void hasValidationError()

This method provides a synchronous way of checking the validation state.
caplin.presenter.property.EditableProperty setUserEnteredValue(Object userEnteredValue)

Accepts a user entered value that may need to be parsed before calling #setValue.
void setValue(Variant value)

Sets the unformatted value for this property and notifies listeners of the change.
Methods implemented from class caplin.core.ValidationResultListener:
onValidationResultReceived

Constructor Detail

► caplin.presenter.property.EditableProperty(Object value)

Constructs a new EditableProperty instance.

Parameters
Object value (optional) The default value for this property.

Method Detail

► caplin.presenter.property.EditableProperty addParser(caplin.core.Parser parser, Object config)

Adds a caplin.core.Parser that will be run each time the user enters a new value.

Parsers allow user input to be normalized prior to validation. For example, the user may be allowed to enter '1M' into an amount field, and a parser might convert this to '1000000' before it is validated by a numeric validator.

Any number of parsers can be added to an editable property, and will be applied in the same way that production rules are applied in production rule systems:

  1. The parsers will be iterated one by one in the same order in which they were added.
  2. If any parser is able to produce a new value from the input, then this value becomes the current value and the process restarts at step 1.
  3. Once a clean run through all the parsers is achieved (with none of them available to produce new input) the parsing phase is complete.

By configuring a number of simple parsers in the same way as production rules are used, complex input handling can be supported.

Parameters
caplin.core.Parser parser the caplin.core.Parser being added.
Object config (optional) Any additional configuration for the parser.

► caplin.presenter.property.PropertyListener addValidationCompleteListener(Object listener, String methodName, boolean notifyImmediately)

A convenience method that allows validation complete listeners to be added for objects that do not themselves implement caplin.presenter.property.PropertyListener.

Listeners added using addValidationCompleteListener() will only be notified when caplin.presenter.property.PropertyListener#onValidationComplete fires, and will not be notified if any of the other caplin.presenter.property.PropertyListener call-backs fire. The advantage to using this method is that objects can choose to listen to call-back events on multiple properties.

Parameters
Object listener The listener to be added.
String methodName The name of the method on the listener that will be invoked each time validation is successful.
boolean notifyImmediately (optional) Whether to invoke the listener immediately for the current value.
Returns
{caplin.presenter.property.PropertyListener} The added property listener.

► caplin.presenter.property.PropertyListener addValidationErrorListener(Object listener, String methodName, boolean notifyImmediately)

A convenience method that allows validation error listeners to be added for objects that do not themselves implement caplin.presenter.property.PropertyListener.

Listeners added using addValidationErrorListener() will only be notified when caplin.presenter.property.PropertyListener#onValidationError fires, and will not be notified if any of the other caplin.presenter.property.PropertyListener call-backs fire. The advantage to using this method is that objects can choose to listen to call-back events on multiple properties.

The invoked method will be passed two arguments:

  • vPropertyValue — The current value of the property.
  • sErrorMessage — The failure message.

Parameters
Object listener The listener to be added.
String methodName The name of the method on the listener that will be invoked each time there is a validation error.
boolean notifyImmediately (optional) Whether to invoke the listener immediately for the current value.
Returns
{caplin.presenter.property.PropertyListener} The added property listener.

► caplin.presenter.property.PropertyListener addValidationSuccessListener(Object listener, String methodName, boolean notifyImmediately)

A convenience method that allows validation success listeners to be added for objects that do not themselves implement caplin.presenter.property.PropertyListener.

Listeners added using addValidationSuccessListener() will only be notified when caplin.presenter.property.PropertyListener#onValidationSuccess fires, and will not be notified if any of the other caplin.presenter.property.PropertyListener call-backs fire. The advantage to using this method is that objects can choose to listen to call-back events on multiple properties.

Parameters
Object listener The listener to be added.
String methodName The name of the method on the listener that will be invoked each time validation is successful.
boolean notifyImmediately (optional) Whether to invoke the listener immediately for the current value.
Returns
{caplin.presenter.property.PropertyListener} The added property listener.

► caplin.presenter.property.EditableProperty addValidator(caplin.core.Validator validator, Object config)

Adds a caplin.core.Validator that will be run each time the user enters a new value.

Validators allow users to be immediately informed when any of their input is invalid. The caplin.presenter.node.Field, caplin.presenter.node.SelectionField and caplin.presenter.node.MultiSelectionField classes all listen to the validation call-backs on caplin.presenter.property.PropertyListener and maintain hasError and failureMessage properties that can be displayed within the view.

Parameters
caplin.core.Validator validator The caplin.core.Validator being added.
Object config (optional) Any additional configuration for the validator.
Returns
{caplin.presenter.property.EditableProperty} The editable property

► void forceValidation()

Force the property to be re-validated.

This method is useful for code that wishes to perform cross-property validation — it is used by the caplin.presenter.validator.CrossValidationPropertyBinder class for example.

► void hasValidationError()

This method provides a synchronous way of checking the validation state.

► caplin.presenter.property.EditableProperty setUserEnteredValue(Object userEnteredValue)

Accepts a user entered value that may need to be parsed before calling #setValue.

Parameters
Object userEnteredValue The unparsed value to set.

► void setValue(Variant value)

Sets the unformatted value for this property and notifies listeners of the change.

This method is the same as caplin.presenter.property.WritableProperty#setValue, except that validation will also be performed.

Parameters
Variant value The value to set.
See
caplin.presenter.property.WritableProperty#setValue