API Docs for: 2.1.2
Show:

Property Class

Defined in: src\model.js:426
Module: Model

A Property is a name value pair belonging to a Model.

Constructor

Property

(
  • name
  • value
  • parent
  • metadata
)
private

Defined in src\model.js:426

Parameters:

  • name String

    The name of the property

  • value String, Boolean, Number, null, Date, Function, Object

    The Property Value

  • parent [Model]

    The parent property

  • metadata Object

    The 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

Methods

destroy

(
  • suppressNotifications?
)
Property

Defined in src\model.js:638

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? Boolean

    indicates if listeners should be notified of destroy.

Returns:

Property: The deleted Property.

getFormattedValue

() Any

Defined in src\model.js:520

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:

Any: The formatted Value

getMetadata

() Object

Defined in src\model.js:760

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:

Object: A map of metadata properties associated with this.

getName

() String

Defined in src\model.js:539

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:

String: The fully qualified name of this.

Example:

defaultModel.getName();              // returns "/root"
defaultModel.property1.getName();    // returns "/root/property1"
namedRoot.property1.getName();       // returns "/customName/property1"

For more examples see: testGetNameMethod

getShortName

() String

Defined in src\model.js:561

The given name of the property.

Returns:

String: The given name of the property.

getValue

() String, Boolean, Number, null, Date, Function

Defined in src\model.js:502

Gets the value of the property.

Returns:

String, Boolean, Number, null, Date, Function: The value of the property

hasValidator

() Boolean

Defined in src\model.js:777

Determine if this has a validation function associated with it.

Returns:

Boolean: True if this has a validator associated with it. False otherwise.

Example:

For examples see: testPropertyValidationFunction

off

(
  • events
  • callback?
)
Property

Defined in src\model.js:730

Removes all instances of the given callback on the given events on this.

Parameters:

  • events String

    One or more space separated eventNames

  • callback? Function

    The function to remove. if not specified all callbacks are removed

Returns:

Property: Returns this for Object chaining.

on

(
  • events
  • callback
)
Property

Defined in src\model.js:700

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 String

    One or more space separated eventNames

  • callback Function

    The function to execute when the given event is triggered

Returns:

Property: Returns this for Object chaining.

onChange

(
  • callback
  • listenToChildren?
)

Defined in src\model.js:608

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 Function

    The function to be called if the value of this changes. The callback function will be passed the following arguments (oldValue, newValue, propertyName)

  • listenToChildren? Boolean

    Registers 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?
)
this

Defined in src\model.js:573

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, Object

    The Value you want to assign to the Property.

  • suppressNotifications? Boolean

    indicates if listeners should be notified of change.

Returns:

this: this for method chaining.

Example:

For more examples see: testPrimitiveSetGet, testComplexChangePropertyValue and testSuppressNotifications

trigger

(
  • eventName
  • ...eventArgs?
)
Property

Defined in src\model.js:684

Triggers the given event on this. Passing the optional argument.

Parameters:

  • eventName String

    The name of the event.

  • ...eventArgs? Any

    Any number of additional parameters to pass to the registered event callback

Returns:

Property: Returns this for Object chaining.

validateValue

(
  • value
)
Boolean

Defined in src\model.js:791

Determines if the given value will pass the validation function of this.

Parameters:

  • value String, Boolean, Number, null, Date, Function

    A value to test against the validation function if it exists.

Returns:

Boolean: The result of passing value against the validation function if it exists. True otherwise.

Example:

For examples see: testPropertyValidationFunction