Smart Polling

attribute  1.0.0

Smart Polling > attribute > Attribute
Search:
 
Filters

Class Attribute - uses Event.Target

Attribute provides managed attribute support.

The class is designed to be augmented onto a host class, and allows the host to support get/set methods for attributes, initial configuration support and attribute change events.

Attributes added to the host can:

  • Be defined as read-only.
  • Be defined as write-once.
  • Be defined with a set function, used to manipulate values passed to Attribute's set method, before they are stored.
  • Be defined with a validator function, to validate values before they are stored.
  • Be defined with a get function, which can be used to manipulate stored values, before they are returned by Attribute's get method.
  • Specify if and how they should be cloned on 'get' (see Attribute.CLONE for supported clone modes).

See the addAtt method, for details about how to add attributes with a specific configuration

Properties

CLONE - static final Object

Constants for clone formats supported by Attribute.

By default attribute values returned by the get method are not cloned. However setting the attribute's "clone" property to:

Attribute.CLONE.DEEP
Will result in a deep cloned value being returned (using YUI's clone method). This can be expensive for complex objects.
Attribute.CLONE.SHALLOW
Will result in a shallow cloned value being returned (using YUI's merge method).
Attribute.CLONE.IMMUTABLE
Will result in a deep cloned value being returned when using the get method. Additionally users will not be able to set sub values of the attribute using the complex attribute notation (obj.set("x.y.z, 5)). However the value of the attribute can be changed, making it different from a READONLY attribute.
Attribute.CLONE.NONE
The value will not be cloned, resulting in a reference to the stored value being passed back, if the value is an object. This is the default behavior.

Methods

_initAtts

protected void _initAtts ( cfg , initValues )
Configures attributes, and sets initial values
Parameters:
cfg <Object> Attribute configuration object literal
initValues <Object> Name/value hash of initial values to apply
Returns: void

_set

protected Object _set ( )
Allows setting of readOnly/writeOnce attributes.
Returns: Object
Reference to the host object
Chainable: This method is chainable.

addAtt

void addAtt ( name , config )

Adds an attribute, with the provided configuration to the host object. Intended to be used by the host object to setup it's set of available attributes.

The config argument object literal supports the following optional properties:

value <Any>
The initial value to set on the attribute
readOnly <Boolean>
Whether or not the attribute is read only. Attributes having readOnly set to true cannot be set by invoking the set method.
writeOnce <Boolean>
Whether or not the attribute is "write once". Attributes having writeOnce set to true, can only have their values set once, be it through the default configuration, constructor configuration arguments, or by invoking set.
set <Function>
The setter function to be invoked (within the context of the host object) before the attribute is stored by a call to the set method. The value returned by the set function will be the finally stored value.
get <Function>
The getter function to be invoked (within the context of the host object) before the stored values is returned to a user invoking the get method for the attribute. The value returned by the get function is the final value which will be returned to the user when they invoke get.
validator <Function>
The validator function which is invoked prior to setting the stored value. Returning false from the validator function will prevent the value from being stored
clone <int>
If and how the value returned by a call to the get method, should be de-referenced from the stored value. By default values are not cloned, and hence a call to get will return a reference to the stored value. See Attribute.CLONE for more details about the clone options available
Parameters:
name <String> The attribute key
config <Object> (optional) An object literal specifying the configuration for the attribute. NOTE: The config object is modified when adding an attribute, so if you need to protect the original values, you will need to merge or clone the object.
Returns: void

get

Any get ( key )
Returns the current value of the attribute. If the attribute has been configured with a 'get' handler, this method will delegate to the 'get' handler to obtain the value of the attribute. The 'get' handler will be passed the current value of the attribute as the only argument.
Parameters:
key <String> The attribute whose value will be returned. If the value of the attribute is an Object, dot notation can be used to obtain the value of a property of the object (e.g. get("x.y.z"))
Returns: Any
The current value of the attribute

getAtts

Object getAtts ( Optional. )
Gets multiple attribute values.
Parameters:
Optional. <Array> An array of attribute names, whose values are required. If omitted, all attribute values are returned.
Returns: Object
A hash of attributes: name/value pairs

on

Event.Handle on ( type , fn , context , args* )

Alias for the Event.Target subscribe method.

Subscribers using this method to listen for attribute change events will be notified just before the state of the attribute has been modified, and before the default handler has been invoked.

The after method, inherited from Event Target, can be used by subscribers who wish to be notified after the attribute's value has changed.

Parameters:
type <String> The event type. For attribute change events, the event type is "[Attribute Name]Change", e.g. for the attribute "enabled", the event type will be "enabledChange".
fn <Function> The subscribed function to invoke
context <Object> Optional execution context
args* <Any*> 0..n additional arguments to append to supply to the subscribed function when the event fires.
Returns: Event.Handle
The handle object for unsubscribing the subscriber from the event.

removeAtt

void removeAtt ( name )
Removes an attribute.
Parameters:
name <String> The attribute key
Returns: void

reset

void reset ( name )
Resets the given attribute or all attributes to the initial value.
Parameters:
name <String> optional An attribute to reset. If omitted, all attributes are reset
Returns: void

set

Object set ( name , value , opts )
Sets the value of an attribute.
Parameters:
name <String> The name of the attribute. Note, if the value of the attribute is an Object, dot notation can be used to set the value of a property within the object (e.g. set("x.y.z", 5)), if the attribute has not been declared as an immutable attribute (see Attribute.CLONE).
value <Any> The value to apply to the attribute
opts <Object> Optional event data. This object will be mixed into the event facade passed as the first argument to subscribers of attribute change events
Returns: Object
Reference to the host object
Chainable: This method is chainable.

setAtts

void setAtts ( atts )
Sets multiple attribute values.
Parameters:
atts <Object> A hash of attributes: name/value pairs
Returns: void

Classes

Properties

Copyright © 2009 Yahoo! Inc. All rights reserved.