Yahoo! UI Library

attribute  3.0.0

Yahoo! UI Library > attribute > Attribute
Search:
 
Filters

Class Attribute - uses EventTarget

Attribute provides configurable attribute support along with attribute change events. It is designed to be augmented on to a host class, and provides the host with the ability to configure attributes to store and retrieve state, along with attribute change events.

For example, attributes added to the host can be configured:

  • As read only.
  • As write once.
  • With a setter function, which can be used to manipulate values passed to Attribute's set method, before they are stored.
  • With a getter function, which can be used to manipulate stored values, before they are returned by Attribute's get method.
  • With a validator function, to validate values before they are stored.

See the addAttr method, for the complete set of configuration options available for attributes

.

NOTE: Most implementations will be better off extending the Base class, instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration of attributes for derived classes, accounting for values passed into the constructor.

Properties

Attribute._ATTR_CFG - protected static Array

The list of properties which can be configured for each attribute (e.g. setter, getter, writeOnce etc.). This property is used internally as a whitelist for faster Y.mix operations.

Attribute.INVALID_VALUE - static final Object

The value to return from an attribute setter in order to prevent the set from going through.

You can return this value from your setter if you wish to combine validator and setter functionality into a single setter function, which either returns the massaged value to be stored or Attribute.INVALID_VALUE to prevent invalid values from being stored.

Methods

_addAttrs

private void _addAttrs ( cfgs , values , lazy )
Implementation behind the public addAttrs method. This method is invoked directly by get if it encounters a scenario in which an attribute's valueFn attempts to obtain the value an attribute in the same group of attributes, which has not yet been added (on demand initialization).
Parameters:
cfgs <Object> An object with attribute name/configuration pairs.
values <Object> An object with attribute name/value pairs, defining the initial values to apply. Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
lazy <boolean> Whether or not to delay the intialization of these attributes until the first call to get/set. Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration. See addAttr.

_addLazyAttr

private void _addLazyAttr ( name )
Finishes initializing an attribute which has been lazily added.
Parameters:
name <Object> The name of the attribute

_defAttrChangeFn

private void _defAttrChangeFn ( e )
Default function for attribute change events.
Parameters:
e <EventFacade> The event object for attribute change events.

_fireAttrChange

private void _fireAttrChange ( attrName , subAttrName , currVal , newVal , opts )
Utility method to help setup the event payload and fire the attribute change event.
Parameters:
attrName <String> The name of the attribute
subAttrName <String> The full path of the property being changed, if this is a sub-attribute value being change. Otherwise null.
currVal <Any> The current value of the attribute
newVal <Any> The new value of the attribute
opts <Object> Any additional event data to mix into the attribute change event's event facade.

_getAttr

protected Any _getAttr ( name )
Provides the common implementation for the public get method, allowing Attribute hosts to over-ride either method. See get for argument details.
Parameters:
name <String> The name of the attribute.
Returns: Any
The value of the attribute.
Chainable: This method is chainable.

_getAttrInitVal

private Any _getAttrInitVal ( attr , cfg , initValues )
Returns the initial value of the given attribute from either the default configuration provided, or the over-ridden value if it exists in the set of initValues provided and the attribute is not read-only.
Parameters:
attr <String> The name of the attribute
cfg <Object> The attribute configuration object
initValues <Object> The object with simple and complex attribute name/value pairs returned from _normAttrVals
Returns: Any
The initial value of the attribute.

_getAttrs

protected Object _getAttrs ( attrs )
Implementation behind the public getAttrs method, to get multiple attribute values.
Parameters:
attrs <Array | boolean> Optional. An array of attribute names. If omitted, all attribute values are returned. If set to true, all attributes modified from their initial values are returned.
Returns: Object
An object with attribute name/value pairs.

_getStateVal

private Any _getStateVal ( name )
Gets the stored value for the attribute, from either the internal state object, or the state proxy if it exits
Parameters:
name <String> The name of the attribute
Returns: Any
The stored value of the attribute

_isLazyAttr

private boolean _isLazyAttr ( name )
Checks whether or not the attribute is one which has been added lazily and still requires initialization.
Parameters:
name <String> The name of the attribute
Returns: boolean
true if it's a lazily added attribute, false otherwise.

_normAttrVals

private Object _normAttrVals ( valueHash )
Utility method to split out simple attribute name/value pairs ("x") from complex attribute name/value pairs ("x.y.z"), so that complex attributes can be keyed by the top level attribute name.
Parameters:
valueHash <Object> An object with attribute name/value pairs
Returns: Object
An object literal with 2 properties - "simple" and "complex", containing simple and complex attribute values respectively keyed by the top level attribute name, or null, if valueHash is falsey.

_protectAttrs

protected Object _protectAttrs ( attrs )
Utility method to protect an attribute configuration hash, by merging the entire object and the individual attr config objects.
Parameters:
attrs <Object> A hash of attribute to configuration object pairs.
Returns: Object
A protected version of the attrs argument.

_set

protected Object _set ( name , val , opts )
Allows setting of readOnly/writeOnce attributes. See set for argument details.
Parameters:
name <String> The name of the attribute.
val <Any> The value to set the attribute to.
opts <Object> (Optional) Optional event data to be mixed into the event facade passed to subscribers of the attribute's change event.
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

_setAttr

protected Object _setAttr ( name , value , opts , force )
Provides the common implementation for the public set and protected _set methods. See set for argument details.
Parameters:
name <String> The name of the attribute.
value <Any> The value to set the attribute to.
opts <Object> (Optional) Optional event data to be mixed into the event facade passed to subscribers of the attribute's change event.
force <boolean> If true, allows the caller to set values for readOnly or writeOnce attributes which have already been set.
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

_setAttrs

protected Object _setAttrs ( attrs )
Implementation behind the public setAttrs method, to set multiple attribute values.
Parameters:
attrs <Object> An object with attributes name/value pairs.
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

_setAttrVal

private booolean _setAttrVal ( attrName , subAttrName , prevVal , newVal )
Updates the stored value of the attribute in the privately held State object, if validation and setter passes.
Parameters:
attrName <String> The attribute name.
subAttrName <String> The sub-attribute name, if setting a sub-attribute property ("x.y.z").
prevVal <Any> The currently stored value of the attribute.
newVal <Any> The value which is going to be stored.
Returns: booolean
true if the new attribute value was stored, false if not.

_setStateVal

private void _setStateVal ( name , value )
Sets the stored value for the attribute, in either the internal state object, or the state proxy if it exits
Parameters:
name <String> The name of the attribute
value <Any> The value of the attribute

addAttr

Object addAttr ( name , config , lazy )

Adds an attribute with the provided configuration to the host object.

The config argument object supports the following properties:

value <Any>
The initial value to set on the attribute
valueFn <Function>
A function, which will return the initial value to set on the attribute. This is useful for cases where the attribute configuration is defined statically, but needs to reference the host instance ("this") to obtain an initial value. If defined, this precedence over the value property.
readOnly <boolean>
Whether or not the attribute is read only. Attributes having readOnly set to true cannot be modified 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.
setter <Function>
The setter function used to massage or normalize the value passed to the set method for the attribute. The value returned by the setter will be the final stored value. Returning Attribute.INVALID_VALUE, from the setter will prevent the value from being stored.
getter <Function>
The getter function used to massage or normalize the value returned by the get method for the attribute. The value returned by the getter function is the value which will be returned to the user when they invoke get.
validator <Function>
The validator function invoked prior to setting the stored value. Returning false from the validator function will prevent the value from being stored.
broadcast <int>
If and how attribute change events for this attribute should be broadcast. See CustomEvent's broadcast property for valid values. By default attribute change events are not broadcast.
lazyAdd <boolean>
Whether or not to delay initialization of the attribute until the first call to get/set it. This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through the addAttrs method.

The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with the context ("this") set to the host object.

Configuration properties outside of the list mentioned above are considered private properties used internally by attribute, and are not intended for public use.

Parameters:
name <String> The name of the attribute.
config <Object> An object with attribute configuration property/value pairs, specifying the configuration for the attribute.

NOTE: The configuration object is modified when adding an attribute, so if you need to protect the original values, you will need to merge the object.

lazy <boolean> (optional) Whether or not to add this attribute lazily (on the first call to get/set).
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

addAttrs

Object addAttrs ( cfgs , values , lazy )
Configures a group of attributes, and sets initial values.

NOTE: This method does not isolate the configuration object by merging/cloning. The caller is responsible for merging/cloning the configuration object if required.

Parameters:
cfgs <Object> An object with attribute name/configuration pairs.
values <Object> An object with attribute name/value pairs, defining the initial values to apply. Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
lazy <boolean> Whether or not to delay the intialization of these attributes until the first call to get/set. Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration. See addAttr.
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

attrAdded

boolean attrAdded ( name )
Checks if the given attribute has been added to the host
Parameters:
name <String> The name of the attribute to check.
Returns: boolean
true if an attribute with the given name has been added, false if it hasn't. This method will return true for lazily added attributes.

get

Any get ( name )
Returns the current value of the attribute. If the attribute has been configured with a 'getter' function, this method will delegate to the 'getter' to obtain the value of the attribute.
Parameters:
name <String> The name of the attribute. 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 value of the attribute

getAttrs

Object getAttrs ( attrs )
Gets multiple attribute values.
Parameters:
attrs <Array | boolean> Optional. An array of attribute names. If omitted, all attribute values are returned. If set to true, all attributes modified from their initial values are returned.
Returns: Object
An object with attribute name/value pairs.

modifyAttr

void modifyAttr ( name , config )
Updates the configuration of an attribute which has already been added.

The properties which can be modified through this interface are limited to the following subset of attributes, which can be safely modified after a value has already been set on the attribute: readOnly, writeOnce, broadcast and getter.

Parameters:
name <String> The name of the attribute whose configuration is to be updated.
config <Object> An object with configuration property/value pairs, specifying the configuration properties to modify.

removeAttr

void removeAttr ( name )
Removes an attribute from the host object
Parameters:
name <String> The name of the attribute to be removed.

reset

Object reset ( name )
Resets the attribute (or all attributes) to its initial value, as long as the attribute is not readOnly, or writeOnce.
Parameters:
name <String> Optional. The name of the attribute to reset. If omitted, all attributes are reset.
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

set

Object set ( name , value , opts )
Sets the value of an attribute.
Parameters:
name <String> The name of the attribute. If the current 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)).
value <Any> The value to set the attribute to.
opts <Object> (Optional) Optional event data to be mixed into the event facade passed to subscribers of the attribute's change event. This can be used as a flexible way to identify the source of a call to set, allowing the developer to distinguish between set called internally by the host, vs. set called externally by the application developer.
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

setAttrs

Object setAttrs ( attrs )
Sets multiple attribute values.
Parameters:
attrs <Object> An object with attributes name/value pairs.
Returns: Object
A reference to the host object.
Chainable: This method is chainable.

Classes

Copyright © 2009 Yahoo! Inc. All rights reserved.