← Back to branch summary

~bac/juju-gui/trunkcopy

« back to all changes in this revision

Viewing changes to lib/yui/build/attribute-core/attribute-core-debug.js

  • Committer: kapil.foss at gmail
  • Date: 2012-07-13 18:45:59 UTC
  • Revision ID: kapil.foss@gmail.com-20120713184559-2xl7be17egsrz0c9
reshape

Show diffs side-by-side

added added

removed removed

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