diff -r 000000000000 -r 40c8f766c9b8 src/cm/media/js/lib/yui/yui_3.0.0b1/api/Attribute.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/cm/media/js/lib/yui/yui_3.0.0b1/api/Attribute.html Mon Nov 23 15:14:29 2009 +0100 @@ -0,0 +1,1691 @@ + + + + + API: attribute Attribute (YUI Library) + + + + + + + + + + +
+
+

Yahoo! UI Library

+

attribute  3.0.0b1

+ 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 onto 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. +
+
+ +
+
Returns: + + void +
+
+
+ + + + +
+ +
+
+
+
+

+ _addLazyAttr

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

+ _defAttrChangeFn

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

+ _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. +
+
+ +
+
Returns: + + void +
+
+
+ + + + +
+ +
+
+
+
+

+ _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 _splitAttrVals +
+
+ +
+
Returns: + + Any +
+
The initial 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.
+
+ + + + +
+ +
+
+
+
+

+ _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. +
+ + + +
+ +
+
+
+
+

+ _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.
+
+ + + + +
+ +
+
+
+
+

+ _splitAttrVals

+
+ + private + + + Object + _splitAttrVals + ( + + + 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.
+
+ + + + +
+ +
+
+
+
+

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

+
+ +
+ +
+
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. +
+
+ +
+
Returns: + + void +
+
+
+ + + + +
+ +
+
+
+
+

+ removeAttr

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

+ 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, + + + _parseType, + + + addTarget, + + + after, + + + before, + + + bubble, + + + detach, + + + detachAll, + + + fire, + + + getEvent, + + + on, + + + publish, + + + removeTarget, + + + subscribe, + + + unsubscribe, + + + unsubscribeAll + + +
+
+
+
+ +
+ + +
+ +
+ +
+ +
+
+
+
+ + + +
+

Classes

+ +
+ +
+

Files

+ +
+ + + + + + + +
+
+
+
+
+ Copyright © 2009 Yahoo! Inc. All rights reserved. +
+
+ + +