cf2:ObservableProperty

Purpose

An observable property is an object that contains a single value, and if modified will send events to any registered handlers. Each property has an owner that is supplied on the constructor, and a set of creation options.

Exported Features

cf2:ObservableProperty

Imported Features

cf2:EventTarget

JavaScript

This component is provided by V$.ObsProp. It mixes in methods from cf2:EventTarget and adds the following new methods:

ObsProp(owner, name, options, results?)

Initializes the observable property.

Parameter	Description	Type
owner	The owner of the property, used when initializing event options. May be null.	Map
name	The name of the property.	String
options	The creation options; may be null.	Map
results	The optional output creation results. If not specified or set to null, then it is assumed that the caller is not interested in the output options.	Map

set(value)

Sets the value of the property, and fires the cf2:propertyChange event to all registered handlers. Returns true if the property was changed; false otherwise. If the property is marked as read-only, then an error will be thrown.

Parameter	Description	Type
value	The new value of the property.	any

any get()

Returns the current value of the property.

boolean getName()

Returns the name of the property.

boolean getOwner()

Returns the owner of the property.

boolean isReadOnly()

Returns the read-only state of the property.

boolean bind(other)

Binds two properties together. The original property will be updated to match the selected property whenever the latter changes. If the original property is read-only, then an error will be thrown. Binding of properties is unidirectional, i.e. changes are propagated in one direction.

It is possible to bind two properties to each other, so that changes applied to one of them will affect the other. It will not cause an infinite loop of events because the cf2:propertyChange event is only fired when a property value is actually changed, not when it is set.

Parameter	Description	Type
other	The property to which the selected property is to be bound.	Object

boolean unbind(other)

Unbinds one property from the other. Returns true if the property was successfully unbound from the other property; false otherwise.

Parameter	Description	Type
other	The property from which this property is to be unbound.	Object

void changed()

Indicates that the property has changed. This method must be used to notify any listeners of deep changes.

There are two types of change events. A shallow change occurs when the value that is held by the observable property changes. It involves changing the state of the property directly, i.e. by invoking the set() method, and therefore the property can detect the change automatically and then can fire appropriate notification events. A deep change occurs when the property references an object graph and the state of some object in that graph changes. The observable property cannot detect those changes automatically and therefore the code responsible for detecting the changes must invoke the changed() method.

Properties

The following table lists the options that are available when creating an observable property. All of these options are optional.

Events

The cf2:propertyChange event is fired after the observable property has changed. The table lists its properties.

cf2:propertyChange

Property	Description	Type
target	The observable property that has changed.	ObsProp
opOwner	The owner of the observable property.	Object
opName	The name of the observable property that has been changed.	String
opOldValue	The old value of the observable property.	any
opNewValue	The new value of the observable property.	any
deep	The type of change event. The value of 'true' indicates that the property change event was triggered by a deep change; 'false' indicates that it was triggered by a shallow change. In the latter case the old and new values will be different but in the former they will be the same.	boolean

Example

The following code defines a read-only property.

var options = {readOnly: true, initialValue: "idle"}
var results = {}
var status = new ObsProp(null, "status", options, results);
var update = results.update();
status.get()
>> "idle"
status.set("busy")
>> ERROR: Property 'status' is read-only
update("busy")
status.get()
>> "busy"

Validating properties

Each property can have an optional validator. It is a function that takes two arguments, the first is the property, the second is the new value for this property. The validator checks the supplied value to make sure that it is valid for the selected property, for example, if the property defines the size of the screen, then negative values are invalid.

var validator = function(property, value) {
  if (value < 0) {
    throw "Invalid " + property.getName() + " '" + value + 
      "': Must be greater than or equal to 0";
  }
}
var options = {validator: validator}
var size
size = new ObsProp(null, "size", options, null);
>> ERROR
options = {validator: validator; initialValue: 0}
size = new ObsProp(null, "size", options, null);
size.get()
>> 0
size.set(-1)
>> ERROR: Invalid size '-1': Must be greater than or equal to 0

Related topics

• Common components
• cf2:EventTarget