Yahoo! UI Library

attribute  3.0.0pr2

Yahoo! UI Library > 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

_cloneAttVal

private Any _cloneAttVal ( val , type )

Clone utility method, which will clone the provided value using YUI's merge, or clone utilities based on the clone type provided. See Attribute.CLONE

Parameters:
val <Any> Value to clone
type <int> Clone type to use, See the CLONE property
Returns: Any
The cloned copy of the object, based on the provided type.

_defAttSet

private void _defAttSet ( e )
Default handler implementation for set events
Parameters:
e <Event.Facade> The event object for the custom event
Returns: void

_fireAttChange

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

_getSubAttVal

private Any _getSubAttVal ( path , val )
Retrieves the sub value at the provided path, from the value object provided.
Parameters:
path <Array> A path array, specifying the object traversal path from which to obtain the sub value.
val <Object> The object from which to extract the property value
Returns: Any
The value stored in the path or undefined if not found.

_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

_initAttVal

private Any _initAttVal ( att , cfg , initVales )
Returns the initial value of the given attribute from either the default configuration provided, or the over-ridden value if it exists in the initValues hash provided.
Parameters:
att <String> Attribute name
cfg <Object> Default attribute configuration object literal
initVales <Object> Initial attribute values, provided for the instance
Returns: Any
Initial value of the attribute.

_set

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

_setSubAttVal

private Object _setSubAttVal ( path , val , subval )
Sets the sub value at the provided path on the value object. Returns the modified value object, or undefined if the path is invalid.
Parameters:
path <Array> A path array, specifying the object traversal path at which to set the sub value.
val <Object> The object on which to set the sub value.
subval <Any> The sub value to set.
Returns: Object
The modified object, with the new sub value set, or undefined, if the path was invalid.

_splitAttrValues

private Object _splitAttrValues ( valueHash )
Utility to split out regular attribute values from complex attribute values, so that complex attributes can be keyed by top level attribute name.
Parameters:
valueHash <Object> Name/value hash of initial values
Returns: Object
Object literal with 2 properties - "simple" and "complex", containing simple and complex attribute values respectively keyed by attribute the top level attribute name.

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 © 2008 Yahoo! Inc. All rights reserved.