Class: module:br/presenter/property/EditableProperty

module:br/presenter/property/EditableProperty

EditableProperty is identical to module:br/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

new module:br/presenter/property/EditableProperty(vValue)

Constructs a new EditableProperty instance.
Extends:
Parameters:
Name Type Description
vValue Object (optional) The default value for this property.
Implements:
  • module:br/presenter/validator/ValidationResultListener
Source:

Extends

Methods

addFormatter(oFormatter, mConfig)

Add a module:br/presenter/formatter/Formatter that will be applied to the property before it's rendered to screen.

Any number of formatters can be added to a property, and will be applied in the same order in which the formatters were added.

Parameters:
Name Type Description
oFormatter module:br/presenter/formatter/Formatter The formatter being added.
mConfig Object (optional) Any additional configuration for the formatter.
Inherited From:
Source:

addParser(oParser, mConfig)

Adds a module:br/presenter/parser/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:
Name Type Description
oParser module:br/presenter/parser/Parser the module:br/presenter/parser/Parser being added.
mConfig Object (optional) Any additional configuration for the parser.
Source:

addValidationCompleteListener(fCallback, bNotifyImmediately)

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

Listeners added using addValidationCompleteListener() will only be notified when module:br/presenter/property/PropertyListener#onValidationComplete fires, and will not be notified if any of the other module:br/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:
Name Type Description
fCallback function The call-back that will be invoked each time validation is complete.
bNotifyImmediately boolean (optional) Whether to invoke the listener immediately for the current value.
Source:

addValidationErrorListener(fCallback, bNotifyImmediately)

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

Listeners added using addValidationErrorListener() will only be notified when module:br/presenter/property/PropertyListener#onValidationError fires, and will not be notified if any of the other module:br/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:
Name Type Description
fCallback function The call-back that will be invoked each time there is a validation error.
bNotifyImmediately boolean (optional) Whether to invoke the listener immediately for the current value.
Source:

addValidationSuccessListener(fCallback, bNotifyImmediately)

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

Listeners added using addValidationSuccessListener() will only be notified when module:br/presenter/property/PropertyListener#onValidationSuccess fires, and will not be notified if any of the other module:br/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:
Name Type Description
fCallback function The call-back that will be invoked each time validation is successful.
bNotifyImmediately boolean (optional) Whether to invoke the listener immediately for the current value.
Source:

addValidator(oValidator, mConfig, mValidatorInfo)

Adds a module:br/presenter/validator/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 module:br/presenter/node/Field, module:br/presenter/node/SelectionField and module:br/presenter/node/MultiSelectionField classes all listen to the validation call-backs on module:br/presenter/property/PropertyListener and maintain hasError and failureMessage properties that can be displayed within the view.

Parameters:
Name Type Description
oValidator module:br/presenter/validator/Validator the module:br/presenter/validator/Validator being added.
mConfig Object (optional) Any additional configuration for the validator.
mValidatorInfo Object (optional) Information about the validator gets written here.
Source:

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 module:br/presenter/validator/CrossValidationPropertyBinder class for example.

Source:

getFormattedValue()

Returns the formatted value for this property if any formatters have been attached, otherwise returns the raw property value.
Inherited From:
Source:

getPath()

Returns the path that would be required to bind this property 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:

getRenderedValue()

Returns the rendered value after applying any active formatters, otherwise returns the raw property value.
Inherited From:
Source:

getValue()

Returns the unformatted value for this property.
Inherited From:
Source:

hasValidationError()

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

removeAllListeners()

Remove all previously added module:br/presenter/property/PropertyListener instances.
Inherited From:
Source:

removeListener(oListener)

Remove a previously added module:br/presenter/property/PropertyListener.
Parameters:
Name Type Description
oListener module:br/presenter/property/PropertyListener The listener being removed.
Inherited From:
Source:

removeParser(parser) → {boolean}

Removes module:br/presenter/parser/Parser from parsers array.
Parameters:
Name Type Description
parser Object The parser to remove.
Source:
Returns:
- true if any validator was removed
Type
boolean

removeValidator(mValidatorInfo) → {boolean}

Removes module:br/presenter/validator/Validator from validators array.
Parameters:
Name Type Description
mValidatorInfo Object The validator information returned by addValidator()
Source:
Returns:
- true if any validator was removed
Type
boolean

setUserEnteredValue(vUserEnteredValue)

Accepts a user entered value that may need to be parsed before calling #setValue.
Parameters:
Name Type Description
vUserEnteredValue Object The unparsed value to set.
Source:

setValue(vValue)

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

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

Parameters:
Name Type Description
vValue Variant The value to set.
Overrides:
Source:
See:
  • br.presenter.property.WritableProperty#setValue