attribute-core-debug.js revision 973e2309557e11c2dda6a3f764a503398ac26272
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The State class maintains state for a collection of named items, with
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * a varying number of properties defined.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * It avoids the need to create a separate class for the item, and separate instances
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * of these classes for each item, by storing the state in a 2 level hash table,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * improving performance when the number of items is likely to be large.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @constructor
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @class State
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.State = function() {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Hash of attributes
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @property data
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Adds a property to an item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method add
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param name {String} The name of the item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param key {String} The name of the property.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param val {Any} The value of the property.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai var d = this.data;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Adds multiple properties to an item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method addAll
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param name {String} The name of the item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param o {Object} A hash of property/value pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai for (key in o) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Removes a property from an item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method remove
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param name {String} The name of the item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param key {String} The property to remove.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai var d = this.data;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Removes multiple properties from an item, or remove the item completely.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method removeAll
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param name {String} The name of the item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param o {Object|Array} Collection of properties to delete. If not provided, the entire item is removed.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai var d = this.data;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.each(o || d, function(v, k) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * For a given item, returns the value of the property requested, or undefined if not found.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method get
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param name {String} The name of the item
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param key {String} Optional. The property value to retrieve.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Any} The value of the supplied property.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai var d = this.data;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * For the given item, returns an object with all of the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * item's property/value pairs. By default the object returned
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * is a shallow copy of the stored data, but passing in true
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * as the second parameter will return a reference to the stored
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method getAll
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param name {String} The name of the item
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param reference {boolean} true, if you want a reference to the stored
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} An object with property/value pairs for the item.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai var d = this.data, o;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai o = o || {};
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The attribute module provides an augmentable Attribute implementation, which
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * adds configurable attributes and attribute change events to the class being
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * augmented. It also provides a State class, which is used internally by Attribute,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * but can also be used independently to provide a name/property/value data structure to
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * store state.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @module attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The attribute-core submodule provides the lightest level of attribute handling support
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * without Attribute change events, or lesser used methods such as reset(), modifyAttrs(),
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * and removeAttr().
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @module attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @submodule attribute-core
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai var O = Y.Object,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Externally configurable props
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Used for internal state management
973e2309557e11c2dda6a3f764a503398ac26272Satyen Desai * AttributeCore provides the lightest level of configurable attribute support. It is designed to be
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * augmented on to a host class, and provides the host with the ability to configure
973e2309557e11c2dda6a3f764a503398ac26272Satyen Desai * attributes to store and retrieve state, <strong>but without support for attribute change events</strong>.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>For example, attributes added to the host can be configured:</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <li>As read only.</li>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <li>As write once.</li>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <li>With a setter function, which can be used to manipulate
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <li>With a getter function, which can be used to manipulate stored values,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * before they are returned by Attribute's <a href="#method_get">get</a> method.</li>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <li>With a validator function, to validate values before they are stored.</li>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration
973e2309557e11c2dda6a3f764a503398ac26272Satyen Desai * options available for attributes.</p>
973e2309557e11c2dda6a3f764a503398ac26272Satyen Desai * <p>Object/Classes based on AttributeCore can augment <a href="AttributeEvents.html">AttributeEvents</a>
973e2309557e11c2dda6a3f764a503398ac26272Satyen Desai * (with true for overwrite) and <a href="AttributeExtras.html">AttributeExtras</a> to add attribute event and
973e2309557e11c2dda6a3f764a503398ac26272Satyen Desai * additional, less commonly used attribute methods, such as `modifyAttr`, `removeAttr` and `reset`.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @class AttributeCore
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>The value to return from an attribute setter in order to prevent the set from going through.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>You can return this value from your setter if you wish to combine validator and setter
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * functionality into a single setter function, which either returns the massaged value to be stored or
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * AttributeCore.INVALID_VALUE to prevent invalid values from being stored.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @property INVALID_VALUE
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @type Object
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The list of properties which can be configured for
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * each attribute (e.g. setter, getter, writeOnce etc.).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * This property is used internally as a whitelist for faster
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Y.mix operations.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @property _ATTR_CFG
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @type Array
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai AttributeCore._ATTR_CFG = [SETTER, GETTER, VALIDATOR, VALUE, VALUE_FN, WRITE_ONCE, READ_ONLY, LAZY_ADD, BYPASS_PROXY];
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Constructor logic for attributes. Initializes the host state, and sets up the inital attributes passed to the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * constructor.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _initAttrHost
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai _initAttrHost : function(attrs, values, lazy) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Adds an attribute with the provided configuration to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The config argument object supports the following properties:
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>value <Any></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dd>The initial value to set on the attribute</dd>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>valueFn <Function | String></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>A function, which will return the initial value to set on the attribute. This is useful
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * for cases where the attribute configuration is defined statically, but needs to
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * reference the host instance ("this") to obtain an initial value. If both the value and valueFn properties are defined,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the value returned by the valueFn has precedence over the value property, unless it returns undefined, in which
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * case the value property is used.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>valueFn can also be set to a string, representing the name of the instance method to be used to retrieve the value.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>readOnly <boolean></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dd>Whether or not the attribute is read only. Attributes having readOnly set to true
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * cannot be modified by invoking the set method.</dd>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>writeOnce <boolean> or <string></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Whether or not the attribute is "write once". Attributes having writeOnce set to true,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * can only have their values set once, be it through the default configuration,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * constructor configuration arguments, or by invoking set.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>The writeOnce attribute can also be set to the string "initOnly", in which case the attribute can only be set during initialization
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * (when used with Base, this means it can only be set during construction)</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>setter <Function | String></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>The setter function used to massage or normalize the value passed to the set method for the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The value returned by the setter will be the final stored value. Returning
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <a href="#property_Attribute.INVALID_VALUE">Attribute.INVALID_VALUE</a>, from the setter will prevent
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the value from being stored.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>setter can also be set to a string, representing the name of the instance method to be used as the setter function.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>getter <Function | String></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The getter function used to massage or normalize the value returned by the get method for the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The value returned by the getter function is the value which will be returned to the user when they
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * invoke get.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>getter can also be set to a string, representing the name of the instance method to be used as the getter function.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>validator <Function | String></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The validator function invoked prior to setting the stored value. Returning
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * false from the validator function will prevent the value from being stored.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>validator can also be set to a string, representing the name of the instance method to be used as the validator function.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dt>lazyAdd <boolean></dt>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <dd>Whether or not to delay initialization of the attribute until the first call to get/set it.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the <a href="#method_addAttrs">addAttrs</a> method.</dd>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the context ("this") set to the host object.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <p>Configuration properties outside of the list mentioned above are considered private properties used internally by attribute,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * and are not intended for public use.</p>
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method addAttr
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} config An object with attribute configuration property/value pairs, specifying the configuration for the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <strong>NOTE:</strong> The configuration object is modified when adding an attribute, so if you need
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * to protect the original values, you will need to merge the object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {boolean} lazy (optional) Whether or not to add this attribute lazily (on the first call to get/set).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Adding attribute: ' + name, 'info', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai lazy = (LAZY_ADD in config) ? config[LAZY_ADD] : lazy;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (host.attrAdded(name) && !state.get(name, IS_LAZY_ADD)) { Y.log('Attribute: ' + name + ' already exists. Cannot add it again without removing it first', 'warn', 'attribute'); }
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (!host.attrAdded(name) || state.get(name, IS_LAZY_ADD)) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (config.readOnly && !hasValue) { Y.log('readOnly attribute: ' + name + ', added without an initial value. Value will be set on initial call to set', 'warn', 'attribute');}
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // We'll go through set, don't want to set value in config directly
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Go through set, so that raw values get normalized/validated
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Checks if the given attribute has been added to the host
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method attrAdded
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute to check.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {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.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Returns the current value of the attribute. If the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * has been configured with a 'getter' function, this method will delegate
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * to the 'getter' to obtain the value of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method get
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute. If the value of the attribute is an Object,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * dot notation can be used to obtain the value of a property of the object (e.g. <code>get("x.y.z")</code>)
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Any} The value of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Checks whether or not the attribute is one which has been
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * added lazily and still requires initialization.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _isLazyAttr
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {boolean} true if it's a lazily added attribute, false otherwise.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Finishes initializing an attribute which has been lazily added.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _addLazyAttr
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} name The name of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Sets the value of an attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method set
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute. If the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * current value of the attribute is an Object, dot notation can be used
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * to set the value of a property within the object (e.g. <code>set("x.y.z", 5)</code>).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} value The value to set the attribute to.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Allows setting of readOnly/writeOnce attributes. See <a href="#method_set">set</a> for argument details.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _set
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} val The value to set the attribute to.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Provides the common implementation for the public set and protected _set methods.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * See <a href="#method_set">set</a> for argument details.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _setAttr
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} value The value to set the attribute to.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} opts (Optional) Optional event data to be mixed into
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the event facade passed to subscribers of the attribute's change event.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * This is currently a hack. There's no real need for the AttributeCore implementation
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * to support this parameter, but breaking it out into AttributeEvents, results in
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * additional function hops for the critical path. May change in 3.5.0 PR3.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {boolean} force If true, allows the caller to set values for
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * readOnly or writeOnce attributes which have already been set.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // HACK - no real reason core needs to know about opts, but
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // it adds fn hops if we want to break it out.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Not sure it's worth it for this critical path
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (stateProxy && name in stateProxy && !cfg._bypassProxy) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // TODO: Value is always set for proxy. Can we do any better? Maybe take a snapshot as the initial value for the first call to set?
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Set attribute:' + name + ', aborted; Attribute is writeOnce', 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Set attribute:' + name + ', aborted; Attribute is readOnly', 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (!initializing && !force && writeOnce === INIT_ONLY) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Set attribute:' + name + ', aborted; Attribute is writeOnce: "initOnly"', 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Don't need currVal if initialSet (might fail in custom getter if it always expects a non-undefined/non-null value)
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Set attribute path:' + strPath + ', aborted; Path is invalid', 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // HACK - no real reason core needs to know about _fireAttrChange, but
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // it adds fn hops if we want to break it out. Not sure it's worth it for this critical path
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai this._fireAttrChange(name, strPath, currVal, val, opts);
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai return this;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Provides the common implementation for the public get method,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * allowing Attribute hosts to over-ride either method.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * See <a href="#method_get">get</a> for argument details.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _getAttr
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Any} The value of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // On Demand - Should be rare - handles out of order valueFn references
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Lazy Init
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai val = (getter) ? getter.call(host, val, fullName) : val;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Gets the stored value for the attribute, from either the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * internal state object, or the state proxy if it exits
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _getStateVal
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Any} The stored value of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai return stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY) ? stateProxy[name] : this._state.get(name, VALUE);
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Sets the stored value for the attribute, in either the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * internal state object, or the state proxy if it exits
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _setStateVal
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} value The value of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY)) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Updates the stored value of the attribute in the privately held State object,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * if validation and setter passes.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _setAttrVal
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} attrName The attribute name.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} subAttrName The sub-attribute name, if setting a sub-attribute property ("x.y.z").
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} prevVal The currently stored value of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} newVal The value which is going to be stored.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {booolean} true if the new attribute value was stored, false if not.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai _setAttrVal : function(attrName, subAttrName, prevVal, newVal) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai cfg = this._state.getAll(attrName, true) || {},
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Assume string - trying to keep critical path tight, so avoiding Lang check
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Assume string - trying to keep critical path tight, so avoiding Lang check
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Attribute: ' + attrName + ', setter returned Attribute.INVALID_VALUE for value:' + newVal, 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Attribute: ' + attrName + ', raw value: ' + newVal + ' modified by setter to:' + retVal, 'info', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if(!subAttrName && (newVal === this._getStateVal(attrName)) && !Lang.isObject(newVal)) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Attribute: ' + attrName + ', value unchanged:' + newVal, 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Store value
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('Attribute:' + attrName + ', Validation failed for value:' + newVal, 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Sets multiple attribute values.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method setAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} attrs An object with attributes name/value pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Implementation behind the public setAttrs method, to set multiple attribute values.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _setAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} attrs An object with attributes name/value pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai return this;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Gets multiple attribute values.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method getAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Array | boolean} attrs Optional. An array of attribute names. If omitted, all attribute values are
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * returned. If set to true, all attributes modified from their initial values are returned.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} An object with attribute name/value pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Implementation behind the public getAttrs method, to get multiple attribute values.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _getAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Array | boolean} attrs Optional. An array of attribute names. If omitted, all attribute values are
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * returned. If set to true, all attributes modified from their initial values are returned.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} An object with attribute name/value pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // TODO - figure out how to get all "added"
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai attrs = (attrs && !modifiedOnly) ? attrs : O.keys(host._state.data);
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Go through get, to honor cloning/normalization
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (!modifiedOnly || host._getStateVal(attr) != host._state.get(attr, INIT_VALUE)) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Configures a group of attributes, and sets initial values.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * <strong>NOTE:</strong> This method does not isolate the configuration object by merging/cloning.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The caller is responsible for merging/cloning the configuration object if required.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method addAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} cfgs An object with attribute name/configuration pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} values An object with attribute name/value pairs, defining the initial values to apply.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {boolean} lazy Whether or not to delay the intialization of these attributes until the first call to get/set.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * See <a href="#method_addAttr">addAttr</a>.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Implementation behind the public addAttrs method.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * This method is invoked directly by get if it encounters a scenario
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * in which an attribute's valueFn attempts to obtain the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * value an attribute in the same group of attributes, which has not yet
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * been added (on demand initialization).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _addAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} cfgs An object with attribute name/configuration pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} values An object with attribute name/value pairs, defining the initial values to apply.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {boolean} lazy Whether or not to delay the intialization of these attributes until the first call to get/set.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * See <a href="#method_addAttr">addAttr</a>.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Not Merging. Caller is responsible for isolating configs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Handle simple, complex and user values, accounting for read-only
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai value = host._getAttrInitVal(attr, attrCfg, host._tVals);
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Utility method to protect an attribute configuration
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * hash, by merging the entire object and the individual
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * attr config objects.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _protectAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} attrs A hash of attribute to configuration object pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A protected version of the attrs argument.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Utility method to normalize attribute values. The base implementation
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * simply merges the hash to protect the original.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _normAttrVals
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} valueHash An object with attribute name/value pairs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object}
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai return (valueHash) ? Y.merge(valueHash) : null;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Returns the initial value of the given attribute from
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * either the default configuration provided, or the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * over-ridden value if it exists in the set of initValues
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * provided and the attribute is not read-only.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} attr The name of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} cfg The attribute configuration object
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} initValues The object with simple and complex attribute name/value pairs returned from _normAttrVals
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Any} The initial value of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _getAttrInitVal
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai _getAttrInitVal : function(attr, cfg, initValues) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // init value is provided by the user if it exists, else, provided by the config
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (!cfg.readOnly && initValues && initValues.hasOwnProperty(attr)) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('initValue for ' + attr + ':' + val, 'info', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Utility method to set up initial attributes defined during construction, either through the constructor.ATTRS property, or explicitly passed in.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _initAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // ATTRS support for Node, which is not Base based
42ca760bb9929dcdf6624637a7613f6f1ebcb4b4Satyen Desai baseCoreInst = (!baseInst && BaseCore && Y.instanceOf(this, BaseCore));
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai this.addAttrs(this._protectAttrs(attrs), values, lazy);
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai}, '@VERSION@' );