# Yahoo! UI Library

### attribute 3.3.0

Yahoo! UI Library > attribute > Attribute
Search:
Filters Show Private Show Protected Show Deprecated

## 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.

#### _getAttrCfg

`protected Object _getAttrCfg ( name )`
Returns an object with the configuration properties (and value) for the given attrubute. If attrName is not provided, returns the configuration properties for all attributes.

Parameters:
  `name <String>` Optional. The attribute name. If not provided, the method will return the configuration for all attributes.

Returns: `Object`
  The configuration properties for the given attribute, or all attributes.

#### _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 normalize attribute values. The base implementation simply merges the hash to protect the original.

Parameters:
  `valueHash <Object>` An object with attribute name/value pairs

#### _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 | String>

  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 both the value and valueFn properties are defined, the value returned by the valueFn has precedence over the value property, unless it returns undefined, in which case the value property is used.

  valueFn can also be set to a string, representing the name of the instance method to be used to retrieve the value.

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> or <string>
  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.

  The writeOnce attribute can also be set to the string "initOnly", in which case the attribute can only be set during initialization (when used with Base, this means it can only be set during construction)

setter <Function | String>

  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.

  setter can also be set to a string, representing the name of the instance method to be used as the setter function.

getter <Function | String>

  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.

  getter can also be set to a string, representing the name of the instance method to be used as the getter function.

validator <Function | String>

  The validator function invoked prior to setting the stored value. Returning false from the validator function will prevent the value from being stored.

  validator can also be set to a string, representing the name of the instance method to be used as the validator function.

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.

#### Methods inherited from EventTarget:

`_getType, _monitor, _parseType, addTarget, after, before, bubble, detach, detachAll, fire, getEvent, getTargets, on, once, parseType, publish, removeTarget, subscribe, unsubscribe, unsubscribeAll`

Copyright © 2011 Yahoo! Inc. All rights reserved.