Property Class
A Property is a name value pair belonging to a Model.
Constructor
Property
-
name
-
value
-
parent
-
metadata
Parameters:
-
name
StringThe name of the property
-
value
String, Boolean, Number, null, Date, Function, ObjectThe Property Value
-
parent
[Model]The parent property
-
metadata
ObjectThe metadata associated with the property. You can put any metadata you want. However the following keys have special meaning and are reserved for use by the framework. validator - a function to validate if the new value is valid before it is assigned. url - the resource this model should use to get it's value. Resource must return json. Must be used with refreshRate refreshRate - the interval used to query the url for changes. must be > 0. minimal value used is 100. -1 indicates to only fetch value once. Must be used with url
Item Index
Methods
destroy
-
suppressNotifications?
Removes the property and its children if any from the Model. This will fire the 'destroy' event on this and the 'childDestroyed' event on the parent.
Parameters:
-
suppressNotifications?
Booleanindicates if listeners should be notified of destroy.
Returns:
getFormattedValue
()
Any
Return the formatted value calculated by passing this.getValue() to the this.getMetadata().Formatter function if it exists. If the metadata Formatter does not exist it will fall back to the global Formatter located at Model.Formatter. If that does not exist it will return this.getValue();
Returns:
getMetadata
()
Object
Retrieves the metadata associated with this. The metadata is persisted with the json when you pass true to the toJSON method (eg. this.toJSON(true)). Likewise the metadata will be restored when creating a model from the very same json. Note: the modeljs framework uses the metadata to store attributes associated the properties that is uses. As a result the following keys have special meaning. [validator, Formatter, name, url, refreshRate, isJSONPurl, doNotPersist, doNotPersistValue, thin]
For example see: testGetMetadataMethod
Returns:
getName
()
String
The fully qualified name of this. The name is calculated by concatenating the name of the parent, "/", and name of this AKA the shortName. To create a named root pass in the name option key to the Model Constructor.
Returns:
Example:
defaultModel.getName(); // returns "/root"
defaultModel.property1.getName(); // returns "/root/property1"
namedRoot.property1.getName(); // returns "/customName/property1"
For more examples see: testGetNameMethod
getShortName
()
String
The given name of the property.
Returns:
getValue
()
String, Boolean, Number, null, Date, Function
Gets the value of the property.
Returns:
hasValidator
()
Boolean
Determine if this has a validation function associated with it.
Returns:
Example:
For examples see: testPropertyValidationFunction
off
-
events
-
callback?
Removes all instances of the given callback on the given events on this.
Parameters:
-
events
StringOne or more space separated eventNames
-
callback?
FunctionThe function to remove. if not specified all callbacks are removed
Returns:
on
-
events
-
callback
Registers the given callback with the given events on this. When the callback is executed it will have it's 'this' context bound to this (ie. the property listening to the event). The first argument will be the property that triggered the event. In most cases these are the same property, unless the event is bubbling up the tree. The final argument is optional and varies depending on event type.
Parameters:
-
events
StringOne or more space separated eventNames
-
callback
FunctionThe function to execute when the given event is triggered
Returns:
onChange
-
callback
-
listenToChildren?
Registers a callback function with the change event of this. When the callback is executed it will have it's 'this' context bound to this (ie. the property listening to the event). The first argument will be the property that triggered the event. The final argument be the oldValue before it was changed.
Parameters:
-
callback
FunctionThe function to be called if the value of this changes. The callback function will be passed the following arguments (oldValue, newValue, propertyName)
-
listenToChildren?
BooleanRegisters the callback with sub property changes as well.
Example:
model.onChange(callback, {listenToChildren: true}); //listens to change events on entire model
model.property1.onChange(callback) //listen to change on property1 only
model.subModel.onChange(callback) //listen to change on subModel only. (ie. via model.subModel.setValue(..))
For more examples see: testOnChangeCallbackWhenSettingToSameValue and testBubbleUpEvents
setValue
-
newValue
-
suppressNotifications?
Called to set the value of a property. If the setValue is the same as the current value, nothing will happen and no change events will be fired. If the value is different it must pass the validator if there is one. If it does pass the validator and the value is changed, all registered listeners will be notified unless the suppressNotifications option indicates otherwise.
Parameters:
-
newValue
String, Boolean, Number, null, Date, Function, ObjectThe Value you want to assign to the Property.
-
suppressNotifications?
Booleanindicates if listeners should be notified of change.
Returns:
Example:
For more examples see: testPrimitiveSetGet, testComplexChangePropertyValue and testSuppressNotifications
trigger
-
eventName
-
...eventArgs?
Triggers the given event on this. Passing the optional argument.
Parameters:
-
eventName
StringThe name of the event.
-
...eventArgs?
AnyAny number of additional parameters to pass to the registered event callback
Returns:
validateValue
-
value
Determines if the given value will pass the validation function of this.
Parameters:
-
value
String, Boolean, Number, null, Date, FunctionA value to test against the validation function if it exists.
Returns:
Example:
For examples see: testPropertyValidationFunction