jssource/src_files/include/javascript/yui3/build/attribute/attribute-base.js

   1 /*
   2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 3.0.0
   6 build: 1549
   7 */
   8 YUI.add('attribute-base', function(Y) {
   9
  10     /**
  11      * The State class maintains state for a collection of named items, with
  12      * a varying number of properties defined.
  13      *
  14      * It avoids the need to create a separate class for the item, and separate instances
  15      * of these classes for each item, by storing the state in a 2 level hash table,
  16      * improving performance when the number of items is likely to be large.
  17      *
  18      * @constructor
  19      * @class State
  20      */
  21     Y.State = function() {
  22         /**
  23          * Hash of attributes
  24          * @property data
  25          */
  26         this.data = {};
  27     };
  28
  29     Y.State.prototype = {
  30
  31         /**
  32          * Adds a property to an item.
  33          *
  34          * @method add
  35          * @param name {String} The name of the item.
  36          * @param key {String} The name of the property.
  37          * @param val {Any} The value of the property.
  38          */
  39         add : function(name, key, val) {
  40             var d = this.data;
  41             d[key] = d[key] || {};
  42             d[key][name] = val;
  43         },
  44
  45         /**
  46          * Adds multiple properties to an item.
  47          *
  48          * @method addAll
  49          * @param name {String} The name of the item.
  50          * @param o {Object} A hash of property/value pairs.
  51          */
  52         addAll: function(name, o) {
  53             var key;
  54             for (key in o) {
  55                 if (o.hasOwnProperty(key)) {
  56                     this.add(name, key, o[key]);
  57                 }
  58             }
  59         },
  60
  61         /**
  62          * Removes a property from an item.
  63          *
  64          * @method remove
  65          * @param name {String} The name of the item.
  66          * @param key {String} The property to remove.
  67          */
  68         remove: function(name, key) {
  69             var d = this.data;
  70             if (d[key] && (name in d[key])) {
  71                 delete d[key][name];
  72             }
  73         },
  74
  75         /**
  76          * Removes multiple properties from an item, or remove the item completely.
  77          *
  78          * @method removeAll
  79          * @param name {String} The name of the item.
  80          * @param o {Object|Array} Collection of properties to delete. If not provided, the entire item is removed.
  81          */
  82         removeAll: function(name, o) {
  83             var d = this.data;
  84
  85             Y.each(o || d, function(v, k) {
  86                 if(Y.Lang.isString(k)) {
  87                     this.remove(name, k);
  88                 } else {
  89                     this.remove(name, v);
  90                 }
  91             }, this);
  92         },
  93
  94         /**
  95          * For a given item, returns the value of the property requested, or undefined if not found.
  96          *
  97          * @method get
  98          * @param name {String} The name of the item
  99          * @param key {String} Optional. The property value to retrieve.
 100          * @return {Any} The value of the supplied property.
 101          */
 102         get: function(name, key) {
 103             var d = this.data;
 104             return (d[key] && name in d[key]) ?  d[key][name] : undefined;
 105         },
 106
 107         /**
 108          * For the given item, returns a disposable object with all of the
 109          * item's property/value pairs.
 110          *
 111          * @method getAll
 112          * @param name {String} The name of the item
 113          * @return {Object} An object with property/value pairs for the item.
 114          */
 115         getAll : function(name) {
 116             var d = this.data, o;
 117
 118             Y.each(d, function(v, k) {
 119                 if (name in d[k]) {
 120                     o = o || {};
 121                     o[k] = v[name];
 122                 }
 123             }, this);
 124
 125             return o;
 126         }
 127     };
 128     /**
 129      * The attribute module provides an augmentable Attribute implementation, which
 130      * adds configurable attributes and attribute change events to the class being
 131      * augmented. It also provides a State class, which is used internally by Attribute,
 132      * but can also be used independently to provide a name/property/value data structure to
 133      * store state.
 134      *
 135      * @module attribute
 136      */
 137
 138     /**
 139      * The attribute-base submodule provides core attribute handling support, with everything
 140      * aside from complex attribute handling in the provider's constructor.
 141      *
 142      * @module attribute
 143      * @submodule attribute-base
 144      */
 145     var O = Y.Object,
 146         Lang = Y.Lang,
 147         EventTarget = Y.EventTarget,
 148
 149         DOT = ".",
 150         CHANGE = "Change",
 151
 152         // Externally configurable props
 153         GETTER = "getter",
 154         SETTER = "setter",
 155         READ_ONLY = "readOnly",
 156         WRITE_ONCE = "writeOnce",
 157         VALIDATOR = "validator",
 158         VALUE = "value",
 159         VALUE_FN = "valueFn",
 160         BROADCAST = "broadcast",
 161         LAZY_ADD = "lazyAdd",
 162         BYPASS_PROXY = "_bypassProxy",
 163
 164         // Used for internal state management
 165         ADDED = "added",
 166         INITIALIZING = "initializing",
 167         INIT_VALUE = "initValue",
 168         PUBLISHED = "published",
 169         DEF_VALUE = "defaultValue",
 170         LAZY = "lazy",
 171         IS_LAZY_ADD = "isLazyAdd",
 172
 173         INVALID_VALUE,
 174         MODIFIABLE = {};
 175
 176         // Properties which can be changed after the attribute has been added.
 177         MODIFIABLE[READ_ONLY] = 1;
 178         MODIFIABLE[WRITE_ONCE] = 1;
 179         MODIFIABLE[GETTER] = 1;
 180         MODIFIABLE[BROADCAST] = 1;
 181
 182     /**
 183      * <p>
 184      * Attribute provides configurable attribute support along with attribute change events. It is designed to be
 185      * augmented on to a host class, and provides the host with the ability to configure attributes to store and retrieve state,
 186      * along with attribute change events.
 187      * </p>
 188      * <p>For example, attributes added to the host can be configured:</p>
 189      * <ul>
 190      *     <li>As read only.</li>
 191      *     <li>As write once.</li>
 192      *     <li>With a setter function, which can be used to manipulate
 193      *     values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>
 194      *     <li>With a getter function, which can be used to manipulate stored values,
 195      *     before they are returned by Attribute's <a href="#method_get">get</a> method.</li>
 196      *     <li>With a validator function, to validate values before they are stored.</li>
 197      * </ul>
 198      *
 199      * <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration
 200      * options available for attributes</p>.
 201      *
 202      * <p><strong>NOTE:</strong> Most implementations will be better off extending the <a href="Base.html">Base</a> class,
 203      * instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration
 204      * of attributes for derived classes, accounting for values passed into the constructor.</p>
 205      *
 206      * @class Attribute
 207      * @uses EventTarget
 208      */
 209     function Attribute() {
 210
 211         var host = this, // help compression
 212             attrs = this.constructor.ATTRS,
 213             Base = Y.Base;
 214
 215         // Perf tweak - avoid creating event literals if not required.
 216         host._ATTR_E_FACADE = {};
 217
 218         EventTarget.call(host, {emitFacade:true});
 219
 220         // _conf maintained for backwards compat
 221         host._conf = host._state = new Y.State();
 222
 223         host._stateProxy = host._stateProxy || null;
 224         host._requireAddAttr = host._requireAddAttr || false;
 225
 226         // ATTRS support for Node, which is not Base based
 227         if ( attrs && !(Base && host instanceof Base)) {
 228             host.addAttrs(this._protectAttrs(attrs));
 229         }
 230     }
 231
 232     /**
 233      * <p>The value to return from an attribute setter in order to prevent the set from going through.</p>
 234      *
 235      * <p>You can return this value from your setter if you wish to combine validator and setter
 236      * functionality into a single setter function, which either returns the massaged value to be stored or
 237      * Attribute.INVALID_VALUE to prevent invalid values from being stored.</p>
 238      *
 239      * @property Attribute.INVALID_VALUE
 240      * @type Object
 241      * @static
 242      * @final
 243      */
 244     Attribute.INVALID_VALUE = {};
 245     INVALID_VALUE = Attribute.INVALID_VALUE;
 246
 247     /**
 248      * The list of properties which can be configured for
 249      * each attribute (e.g. setter, getter, writeOnce etc.).
 250      *
 251      * This property is used internally as a whitelist for faster
 252      * Y.mix operations.
 253      *
 254      * @property Attribute._ATTR_CFG
 255      * @type Array
 256      * @static
 257      * @protected
 258      */
 259     Attribute._ATTR_CFG = [SETTER, GETTER, VALIDATOR, VALUE, VALUE_FN, WRITE_ONCE, READ_ONLY, LAZY_ADD, BROADCAST, BYPASS_PROXY];
 260
 261     Attribute.prototype = {
 262         /**
 263          * <p>
 264          * Adds an attribute with the provided configuration to the host object.
 265          * </p>
 266          * <p>
 267          * The config argument object supports the following properties:
 268          * </p>
 269          *
 270          * <dl>
 271          *    <dt>value &#60;Any&#62;</dt>
 272          *    <dd>The initial value to set on the attribute</dd>
 273          *
 274          *    <dt>valueFn &#60;Function&#62;</dt>
 275          *    <dd>A function, which will return the initial value to set on the attribute. This is useful
 276          *    for cases where the attribute configuration is defined statically, but needs to
 277          *    reference the host instance ("this") to obtain an initial value.
 278          *    If defined, this precedence over the value property.</dd>
 279          *
 280          *    <dt>readOnly &#60;boolean&#62;</dt>
 281          *    <dd>Whether or not the attribute is read only. Attributes having readOnly set to true
 282          *        cannot be modified by invoking the set method.</dd>
 283          *
 284          *    <dt>writeOnce &#60;boolean&#62;</dt>
 285          *    <dd>Whether or not the attribute is "write once". Attributes having writeOnce set to true,
 286          *        can only have their values set once, be it through the default configuration,
 287          *        constructor configuration arguments, or by invoking set.</dd>
 288          *
 289          *    <dt>setter &#60;Function&#62;</dt>
 290          *    <dd>The setter function used to massage or normalize the value passed to the set method for the attribute.
 291          *    The value returned by the setter will be the final stored value. Returning
 292          *    <a href="#property_Attribute.INVALID_VALUE">Attribute.INVALID_VALUE</a>, from the setter will prevent
 293          *    the value from being stored.</dd>
 294          *
 295          *    <dt>getter &#60;Function&#62;</dt>
 296          *    <dd>The getter function used to massage or normalize the value returned by the get method for the attribute.
 297          *    The value returned by the getter function is the value which will be returned to the user when they
 298          *    invoke get.</dd>
 299          *
 300          *    <dt>validator &#60;Function&#62;</dt>
 301          *    <dd>The validator function invoked prior to setting the stored value. Returning
 302          *    false from the validator function will prevent the value from being stored.</dd>
 303          *
 304          *    <dt>broadcast &#60;int&#62;</dt>
 305          *    <dd>If and how attribute change events for this attribute should be broadcast. See CustomEvent's <a href="CustomEvent.html#property_broadcast">broadcast</a> property for
 306          *    valid values. By default attribute change events are not broadcast.</dd>
 307          *
 308          *    <dt>lazyAdd &#60;boolean&#62;</dt>
 309          *    <dd>Whether or not to delay initialization of the attribute until the first call to get/set it.
 310          *    This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through
 311          *    the <a href="#method_addAttrs">addAttrs</a> method.</dd>
 312          *
 313          * </dl>
 314          *
 315          * <p>The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with
 316          * the context ("this") set to the host object.</p>
 317          *
 318          * <p>Configuration properties outside of the list mentioned above are considered private properties used internally by attribute, and are not intended for public use.</p>
 319          *
 320          * @method addAttr
 321          *
 322          * @param {String} name The name of the attribute.
 323          * @param {Object} config An object with attribute configuration property/value pairs, specifying the configuration for the attribute.
 324          *
 325          * <p>
 326          * <strong>NOTE:</strong> The configuration object is modified when adding an attribute, so if you need
 327          * to protect the original values, you will need to merge the object.
 328          * </p>
 329          *
 330          * @param {boolean} lazy (optional) Whether or not to add this attribute lazily (on the first call to get/set).
 331          *
 332          * @return {Object} A reference to the host object.
 333          *
 334          * @chainable
 335          */
 336         addAttr: function(name, config, lazy) {
 337
 338
 339             var host = this, // help compression
 340                 state = host._state,
 341                 value,
 342                 hasValue;
 343
 344             lazy = (LAZY_ADD in config) ? config[LAZY_ADD] : lazy;
 345
 346             if (lazy && !host.attrAdded(name)) {
 347                 state.add(name, LAZY, config || {});
 348                 state.add(name, ADDED, true);
 349             } else {
 350
 351
 352                 if (!host.attrAdded(name) || state.get(name, IS_LAZY_ADD)) {
 353
 354                     config = config || {};
 355
 356                     hasValue = (VALUE in config);
 357
 358
 359                     if(hasValue) {
 360                         // We'll go through set, don't want to set value in _state directly
 361                         value = config.value;
 362                         delete config.value;
 363                     }
 364
 365                     config.added = true;
 366                     config.initializing = true;
 367
 368                     state.addAll(name, config);
 369
 370                     if (hasValue) {
 371                         // Go through set, so that raw values get normalized/validated
 372                         host.set(name, value);
 373                     }
 374
 375                     state.remove(name, INITIALIZING);
 376                 }
 377             }
 378
 379             return host;
 380         },
 381
 382         /**
 383          * Checks if the given attribute has been added to the host
 384          *
 385          * @method attrAdded
 386          * @param {String} name The name of the attribute to check.
 387          * @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.
 388          */
 389         attrAdded: function(name) {
 390             return !!this._state.get(name, ADDED);
 391         },
 392
 393         /**
 394          * Updates the configuration of an attribute which has already been added.
 395          * <p>
 396          * The properties which can be modified through this interface are limited
 397          * to the following subset of attributes, which can be safely modified
 398          * after a value has already been set on the attribute: readOnly, writeOnce,
 399          * broadcast and getter.
 400          * </p>
 401          * @method modifyAttr
 402          * @param {String} name The name of the attribute whose configuration is to be updated.
 403          * @param {Object} config An object with configuration property/value pairs, specifying the configuration properties to modify.
 404          */
 405         modifyAttr: function(name, config) {
 406             var host = this, // help compression
 407                 prop, state;
 408
 409             if (host.attrAdded(name)) {
 410
 411                 if (host._isLazyAttr(name)) {
 412                     host._addLazyAttr(name);
 413                 }
 414
 415                 state = host._state;
 416                 for (prop in config) {
 417                     if (MODIFIABLE[prop] && config.hasOwnProperty(prop)) {
 418                         state.add(name, prop, config[prop]);
 419
 420                         // If we reconfigured broadcast, need to republish
 421                         if (prop === BROADCAST) {
 422                             state.remove(name, PUBLISHED);
 423                         }
 424                     }
 425                 }
 426             }
 427
 428         },
 429
 430         /**
 431          * Removes an attribute from the host object
 432          *
 433          * @method removeAttr
 434          * @param {String} name The name of the attribute to be removed.
 435          */
 436         removeAttr: function(name) {
 437             this._state.removeAll(name);
 438         },
 439
 440         /**
 441          * Returns the current value of the attribute. If the attribute
 442          * has been configured with a 'getter' function, this method will delegate
 443          * to the 'getter' to obtain the value of the attribute.
 444          *
 445          * @method get
 446          *
 447          * @param {String} name The name of the attribute. If the value of the attribute is an Object,
 448          * dot notation can be used to obtain the value of a property of the object (e.g. <code>get("x.y.z")</code>)
 449          *
 450          * @return {Any} The value of the attribute
 451          */
 452         get : function(name) {
 453             return this._getAttr(name);
 454         },
 455
 456         /**
 457          * Checks whether or not the attribute is one which has been
 458          * added lazily and still requires initialization.
 459          *
 460          * @method _isLazyAttr
 461          * @private
 462          * @param {String} name The name of the attribute
 463          * @return {boolean} true if it's a lazily added attribute, false otherwise.
 464          */
 465         _isLazyAttr: function(name) {
 466             return this._state.get(name, LAZY);
 467         },
 468
 469         /**
 470          * Finishes initializing an attribute which has been lazily added.
 471          *
 472          * @method _addLazyAttr
 473          * @private
 474          * @param {Object} name The name of the attribute
 475          */
 476         _addLazyAttr: function(name) {
 477             var state = this._state,
 478                 lazyCfg = state.get(name, LAZY);
 479
 480             state.add(name, IS_LAZY_ADD, true);
 481             state.remove(name, LAZY);
 482             this.addAttr(name, lazyCfg);
 483         },
 484
 485         /**
 486          * Sets the value of an attribute.
 487          *
 488          * @method set
 489          * @chainable
 490          *
 491          * @param {String} name The name of the attribute. If the
 492          * current value of the attribute is an Object, dot notation can be used
 493          * to set the value of a property within the object (e.g. <code>set("x.y.z", 5)</code>).
 494          *
 495          * @param {Any} value The value to set the attribute to.
 496          *
 497          * @param {Object} opts (Optional) Optional event data to be mixed into
 498          * the event facade passed to subscribers of the attribute's change event. This
 499          * can be used as a flexible way to identify the source of a call to set, allowing
 500          * the developer to distinguish between set called internally by the host, vs.
 501          * set called externally by the application developer.
 502          *
 503          * @return {Object} A reference to the host object.
 504          */
 505         set : function(name, val, opts) {
 506             return this._setAttr(name, val, opts);
 507         },
 508
 509         /**
 510          * Resets the attribute (or all attributes) to its initial value, as long as
 511          * the attribute is not readOnly, or writeOnce.
 512          *
 513          * @method reset
 514          * @param {String} name Optional. The name of the attribute to reset.  If omitted, all attributes are reset.
 515          * @return {Object} A reference to the host object.
 516          * @chainable
 517          */
 518         reset : function(name) {
 519             var host = this,  // help compression
 520                 added;
 521
 522             if (name) {
 523                 if (host._isLazyAttr(name)) {
 524                     host._addLazyAttr(name);
 525                 }
 526                 host.set(name, host._state.get(name, INIT_VALUE));
 527             } else {
 528                 added = host._state.data.added;
 529                 Y.each(added, function(v, n) {
 530                     host.reset(n);
 531                 }, host);
 532             }
 533             return host;
 534         },
 535
 536         /**
 537          * Allows setting of readOnly/writeOnce attributes. See <a href="#method_set">set</a> for argument details.
 538          *
 539          * @method _set
 540          * @protected
 541          * @chainable
 542          *
 543          * @param {String} name The name of the attribute.
 544          * @param {Any} val The value to set the attribute to.
 545          * @param {Object} opts (Optional) Optional event data to be mixed into
 546          * the event facade passed to subscribers of the attribute's change event.
 547          * @return {Object} A reference to the host object.
 548          */
 549         _set : function(name, val, opts) {
 550             return this._setAttr(name, val, opts, true);
 551         },
 552
 553         /**
 554          * Provides the common implementation for the public get method,
 555          * allowing Attribute hosts to over-ride either method.
 556          *
 557          * See <a href="#method_get">get</a> for argument details.
 558          *
 559          * @method _getAttr
 560          * @protected
 561          * @chainable
 562          *
 563          * @param {String} name The name of the attribute.
 564          * @return {Any} The value of the attribute.
 565          */
 566         _getAttr : function(name) {
 567             var host = this, // help compression
 568                 fullName = name,
 569                 state = host._state,
 570                 path,
 571                 getter,
 572                 val,
 573                 cfg;
 574
 575             if (name.indexOf(DOT) !== -1) {
 576                 path = name.split(DOT);
 577                 name = path.shift();
 578             }
 579
 580             // On Demand - Should be rare - handles out of order valueFn references
 581             if (host._tCfgs && host._tCfgs[name]) {
 582                 cfg = {};
 583                 cfg[name] = host._tCfgs[name];
 584                 delete host._tCfgs[name];
 585                 host._addAttrs(cfg, host._tVals);
 586             }
 587
 588             // Lazy Init
 589             if (host._isLazyAttr(name)) {
 590                 host._addLazyAttr(name);
 591             }
 592
 593             val = host._getStateVal(name);
 594             getter = state.get(name, GETTER);
 595
 596             val = (getter) ? getter.call(host, val, fullName) : val;
 597             val = (path) ? O.getValue(val, path) : val;
 598
 599             return val;
 600         },
 601
 602         /**
 603          * Provides the common implementation for the public set and protected _set methods.
 604          *
 605          * See <a href="#method_set">set</a> for argument details.
 606          *
 607          * @method _setAttr
 608          * @protected
 609          * @chainable
 610          *
 611          * @param {String} name The name of the attribute.
 612          * @param {Any} value The value to set the attribute to.
 613          * @param {Object} opts (Optional) Optional event data to be mixed into
 614          * the event facade passed to subscribers of the attribute's change event.
 615          * @param {boolean} force If true, allows the caller to set values for
 616          * readOnly or writeOnce attributes which have already been set.
 617          *
 618          * @return {Object} A reference to the host object.
 619          */
 620         _setAttr : function(name, val, opts, force) {
 621             var allowSet = true,
 622                 state = this._state,
 623                 stateProxy = this._stateProxy,
 624                 data = state.data,
 625                 initialSet,
 626                 strPath,
 627                 path,
 628                 currVal;
 629
 630             if (name.indexOf(DOT) !== -1) {
 631                 strPath = name;
 632                 path = name.split(DOT);
 633                 name = path.shift();
 634             }
 635
 636             if (this._isLazyAttr(name)) {
 637                 this._addLazyAttr(name);
 638             }
 639
 640             initialSet = (!data.value || !(name in data.value));
 641
 642             if (stateProxy && name in stateProxy && !this._state.get(name, BYPASS_PROXY)) {
 643                 // 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?
 644                 initialSet = false;
 645             }
 646
 647             if (this._requireAddAttr && !this.attrAdded(name)) {
 648             } else {
 649
 650                 if (!initialSet && !force) {
 651
 652                     if (state.get(name, WRITE_ONCE)) {
 653                         allowSet = false;
 654                     }
 655
 656                     if (state.get(name, READ_ONLY)) {
 657                         allowSet = false;
 658                     }
 659                 }
 660
 661                 if (allowSet) {
 662                     // Don't need currVal if initialSet (might fail in custom getter if it always expects a non-undefined/non-null value)
 663                     if (!initialSet) {
 664                         currVal =  this.get(name);
 665                     }
 666
 667                     if (path) {
 668                        val = O.setValue(Y.clone(currVal), path, val);
 669
 670                        if (val === undefined) {
 671                            allowSet = false;
 672                        }
 673                     }
 674
 675                     if (allowSet) {
 676                         if (state.get(name, INITIALIZING)) {
 677                             this._setAttrVal(name, strPath, currVal, val);
 678                         } else {
 679                             this._fireAttrChange(name, strPath, currVal, val, opts);
 680                         }
 681                     }
 682                 }
 683             }
 684
 685             return this;
 686         },
 687
 688         /**
 689          * Utility method to help setup the event payload and fire the attribute change event.
 690          *
 691          * @method _fireAttrChange
 692          * @private
 693          * @param {String} attrName The name of the attribute
 694          * @param {String} subAttrName The full path of the property being changed,
 695          * if this is a sub-attribute value being change. Otherwise null.
 696          * @param {Any} currVal The current value of the attribute
 697          * @param {Any} newVal The new value of the attribute
 698          * @param {Object} opts Any additional event data to mix into the attribute change event's event facade.
 699          */
 700         _fireAttrChange : function(attrName, subAttrName, currVal, newVal, opts) {
 701             var host = this,
 702                 eventName = attrName + CHANGE,
 703                 state = host._state,
 704                 facade;
 705
 706             if (!state.get(attrName, PUBLISHED)) {
 707                 host.publish(eventName, {
 708                     queuable:false,
 709                     defaultFn:host._defAttrChangeFn,
 710                     silent:true,
 711                     broadcast : state.get(attrName, BROADCAST)
 712                 });
 713                 state.add(attrName, PUBLISHED, true);
 714             }
 715
 716             facade = (opts) ? Y.merge(opts) : host._ATTR_E_FACADE;
 717
 718             facade.type = eventName;
 719             facade.attrName = attrName;
 720             facade.subAttrName = subAttrName;
 721             facade.prevVal = currVal;
 722             facade.newVal = newVal;
 723
 724             host.fire(facade);
 725         },
 726
 727         /**
 728          * Default function for attribute change events.
 729          *
 730          * @private
 731          * @method _defAttrChangeFn
 732          * @param {EventFacade} e The event object for attribute change events.
 733          */
 734         _defAttrChangeFn : function(e) {
 735             if (!this._setAttrVal(e.attrName, e.subAttrName, e.prevVal, e.newVal)) {
 736                 // Prevent "after" listeners from being invoked since nothing changed.
 737                 e.stopImmediatePropagation();
 738             } else {
 739                 e.newVal = this._getStateVal(e.attrName);
 740             }
 741         },
 742
 743         /**
 744          * Gets the stored value for the attribute, from either the
 745          * internal state object, or the state proxy if it exits
 746          *
 747          * @method _getStateVal
 748          * @private
 749          * @param {String} name The name of the attribute
 750          * @return {Any} The stored value of the attribute
 751          */
 752         _getStateVal : function(name) {
 753             var stateProxy = this._stateProxy;
 754             return stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY) ? stateProxy[name] : this._state.get(name, VALUE);
 755         },
 756
 757         /**
 758          * Sets the stored value for the attribute, in either the
 759          * internal state object, or the state proxy if it exits
 760          *
 761          * @method _setStateVal
 762          * @private
 763          * @param {String} name The name of the attribute
 764          * @param {Any} value The value of the attribute
 765          */
 766         _setStateVal : function(name, value) {
 767             var stateProxy = this._stateProxy;
 768             if (stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY)) {
 769                 stateProxy[name] = value;
 770             } else {
 771                 this._state.add(name, VALUE, value);
 772             }
 773         },
 774
 775         /**
 776          * Updates the stored value of the attribute in the privately held State object,
 777          * if validation and setter passes.
 778          *
 779          * @method _setAttrVal
 780          * @private
 781          * @param {String} attrName The attribute name.
 782          * @param {String} subAttrName The sub-attribute name, if setting a sub-attribute property ("x.y.z").
 783          * @param {Any} prevVal The currently stored value of the attribute.
 784          * @param {Any} newVal The value which is going to be stored.
 785          *
 786          * @return {booolean} true if the new attribute value was stored, false if not.
 787          */
 788         _setAttrVal : function(attrName, subAttrName, prevVal, newVal) {
 789
 790             var host = this,
 791                 allowSet = true,
 792                 state = host._state,
 793
 794                 validator = state.get(attrName, VALIDATOR),
 795                 setter = state.get(attrName, SETTER),
 796                 initializing = state.get(attrName, INITIALIZING),
 797                 prevValRaw = this._getStateVal(attrName),
 798
 799                 name = subAttrName || attrName,
 800                 retVal,
 801                 valid;
 802
 803             if (validator) {
 804                 valid = validator.call(host, newVal, name);
 805
 806                 if (!valid && initializing) {
 807                     newVal = state.get(attrName, DEF_VALUE);
 808                     valid = true; // Assume it's valid, for perf.
 809                 }
 810             }
 811
 812             if (!validator || valid) {
 813                 if (setter) {
 814                     retVal = setter.call(host, newVal, name);
 815
 816                     if (retVal === INVALID_VALUE) {
 817                         allowSet = false;
 818                     } else if (retVal !== undefined){
 819                         newVal = retVal;
 820                     }
 821                 }
 822
 823                 if (allowSet) {
 824                     if(!subAttrName && (newVal === prevValRaw) && !Lang.isObject(newVal)) {
 825                         allowSet = false;
 826                     } else {
 827                         // Store value
 828                         if (state.get(attrName, INIT_VALUE) === undefined) {
 829                             state.add(attrName, INIT_VALUE, newVal);
 830                         }
 831                         host._setStateVal(attrName, newVal);
 832                     }
 833                 }
 834
 835             } else {
 836                 allowSet = false;
 837             }
 838
 839             return allowSet;
 840         },
 841
 842         /**
 843          * Sets multiple attribute values.
 844          *
 845          * @method setAttrs
 846          * @param {Object} attrs  An object with attributes name/value pairs.
 847          * @return {Object} A reference to the host object.
 848          * @chainable
 849          */
 850         setAttrs : function(attrs, opts) {
 851             return this._setAttrs(attrs, opts);
 852         },
 853
 854         /**
 855          * Implementation behind the public setAttrs method, to set multiple attribute values.
 856          *
 857          * @method _setAttrs
 858          * @protected
 859          * @param {Object} attrs  An object with attributes name/value pairs.
 860          * @return {Object} A reference to the host object.
 861          * @chainable
 862          */
 863         _setAttrs : function(attrs, opts) {
 864             for (var attr in attrs) {
 865                 if ( attrs.hasOwnProperty(attr) ) {
 866                     this.set(attr, attrs[attr]);
 867                 }
 868             }
 869             return this;
 870         },
 871
 872         /**
 873          * Gets multiple attribute values.
 874          *
 875          * @method getAttrs
 876          * @param {Array | boolean} attrs Optional. An array of attribute names. If omitted, all attribute values are
 877          * returned. If set to true, all attributes modified from their initial values are returned.
 878          * @return {Object} An object with attribute name/value pairs.
 879          */
 880         getAttrs : function(attrs) {
 881             return this._getAttrs(attrs);
 882         },
 883
 884         /**
 885          * Implementation behind the public getAttrs method, to get multiple attribute values.
 886          *
 887          * @method _getAttrs
 888          * @protected
 889          * @param {Array | boolean} attrs Optional. An array of attribute names. If omitted, all attribute values are
 890          * returned. If set to true, all attributes modified from their initial values are returned.
 891          * @return {Object} An object with attribute name/value pairs.
 892          */
 893         _getAttrs : function(attrs) {
 894             var host = this,
 895                 o = {},
 896                 i, l, attr, val,
 897                 modifiedOnly = (attrs === true);
 898
 899             attrs = (attrs && !modifiedOnly) ? attrs : O.keys(host._state.data.added);
 900
 901             for (i = 0, l = attrs.length; i < l; i++) {
 902                 // Go through get, to honor cloning/normalization
 903                 attr = attrs[i];
 904                 val = host.get(attr);
 905
 906                 if (!modifiedOnly || host._getStateVal(attr) != host._state.get(attr, INIT_VALUE)) {
 907                     o[attr] = host.get(attr);
 908                 }
 909             }
 910
 911             return o;
 912         },
 913
 914         /**
 915          * Configures a group of attributes, and sets initial values.
 916          *
 917          * <p>
 918          * <strong>NOTE:</strong> This method does not isolate the configuration object by merging/cloning.
 919          * The caller is responsible for merging/cloning the configuration object if required.
 920          * </p>
 921          *
 922          * @method addAttrs
 923          * @chainable
 924          *
 925          * @param {Object} cfgs An object with attribute name/configuration pairs.
 926          * @param {Object} values An object with attribute name/value pairs, defining the initial values to apply.
 927          * Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
 928          * @param {boolean} lazy Whether or not to delay the intialization of these attributes until the first call to get/set.
 929          * Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration.
 930          * See <a href="#method_addAttr">addAttr</a>.
 931          *
 932          * @return {Object} A reference to the host object.
 933          */
 934         addAttrs : function(cfgs, values, lazy) {
 935             var host = this; // help compression
 936             if (cfgs) {
 937                 host._tCfgs = cfgs;
 938                 host._tVals = host._normAttrVals(values);
 939                 host._addAttrs(cfgs, host._tVals, lazy);
 940                 host._tCfgs = host._tVals = null;
 941             }
 942
 943             return host;
 944         },
 945
 946         /**
 947          * Implementation behind the public addAttrs method.
 948          *
 949          * This method is invoked directly by get if it encounters a scenario
 950          * in which an attribute's valueFn attempts to obtain the
 951          * value an attribute in the same group of attributes, which has not yet
 952          * been added (on demand initialization).
 953          *
 954          * @method _addAttrs
 955          * @private
 956          * @param {Object} cfgs An object with attribute name/configuration pairs.
 957          * @param {Object} values An object with attribute name/value pairs, defining the initial values to apply.
 958          * Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
 959          * @param {boolean} lazy Whether or not to delay the intialization of these attributes until the first call to get/set.
 960          * Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration.
 961          * See <a href="#method_addAttr">addAttr</a>.
 962          */
 963         _addAttrs : function(cfgs, values, lazy) {
 964             var host = this, // help compression
 965                 attr,
 966                 attrCfg,
 967                 value;
 968
 969             for (attr in cfgs) {
 970                 if (cfgs.hasOwnProperty(attr)) {
 971
 972                     // Not Merging. Caller is responsible for isolating configs
 973                     attrCfg = cfgs[attr];
 974                     attrCfg.defaultValue = attrCfg.value;
 975
 976                     // Handle simple, complex and user values, accounting for read-only
 977                     value = host._getAttrInitVal(attr, attrCfg, host._tVals);
 978
 979                     if (value !== undefined) {
 980                         attrCfg.value = value;
 981                     }
 982
 983                     if (host._tCfgs[attr]) {
 984                         delete host._tCfgs[attr];
 985                     }
 986
 987                     host.addAttr(attr, attrCfg, lazy);
 988                 }
 989             }
 990         },
 991
 992         /**
 993          * Utility method to protect an attribute configuration
 994          * hash, by merging the entire object and the individual
 995          * attr config objects.
 996          *
 997          * @method _protectAttrs
 998          * @protected
 999          * @param {Object} attrs A hash of attribute to configuration object pairs.
1000          * @return {Object} A protected version of the attrs argument.
1001          */
1002         _protectAttrs : function(attrs) {
1003             if (attrs) {
1004                 attrs = Y.merge(attrs);
1005                 for (var attr in attrs) {
1006                     if (attrs.hasOwnProperty(attr)) {
1007                         attrs[attr] = Y.merge(attrs[attr]);
1008                     }
1009                 }
1010             }
1011             return attrs;
1012         },
1013
1014         /**
1015          * Utility method to normalize attribute values. The base implementation
1016          * simply merges the hash to protect the original.
1017          *
1018          * @method _normAttrVals
1019          * @param {Object} valueHash An object with attribute name/value pairs
1020          *
1021          * @return {Object}
1022          *
1023          * @private
1024          */
1025         _normAttrVals : function(valueHash) {
1026             return (valueHash) ? Y.merge(valueHash) : null;
1027         },
1028
1029         /**
1030          * Returns the initial value of the given attribute from
1031          * either the default configuration provided, or the
1032          * over-ridden value if it exists in the set of initValues
1033          * provided and the attribute is not read-only.
1034          *
1035          * @param {String} attr The name of the attribute
1036          * @param {Object} cfg The attribute configuration object
1037          * @param {Object} initValues The object with simple and complex attribute name/value pairs returned from _normAttrVals
1038          *
1039          * @return {Any} The initial value of the attribute.
1040          *
1041          * @method _getAttrInitVal
1042          * @private
1043          */
1044         _getAttrInitVal : function(attr, cfg, initValues) {
1045
1046             // init value is provided by the user if it exists, else, provided by the config
1047             var val = (!cfg[READ_ONLY] && initValues && initValues.hasOwnProperty(attr)) ?
1048                             val = initValues[attr] :
1049                             (cfg[VALUE_FN]) ?
1050                                 cfg[VALUE_FN].call(this) :
1051                                 cfg[VALUE];
1052
1053
1054             return val;
1055         }
1056     };
1057
1058     // Basic prototype augment - no lazy constructor invocation.
1059     Y.mix(Attribute, EventTarget, false, null, 1);
1060
1061     Y.Attribute = Attribute;
1062
1063
1064 }, '3.0.0' ,{requires:['event-custom']});