lib/yui/3.5.1/build/attribute-base/attribute-base.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-base', function(Y) {
   8
   9     /**
  10      * The attribute module provides an augmentable Attribute implementation, which
  11      * adds configurable attributes and attribute change events to the class being
  12      * augmented. It also provides a State class, which is used internally by Attribute,
  13      * but can also be used independently to provide a name/property/value data structure to
  14      * store state.
  15      *
  16      * @module attribute
  17      */
  18
  19     /**
  20      * The attribute-base submodule provides core attribute handling support, with everything
  21      * aside from complex attribute handling in the provider's constructor.
  22      *
  23      * @module attribute
  24      * @submodule attribute-base
  25      */
  26
  27     /**
  28      * <p>
  29      * Attribute provides configurable attribute support along with attribute change events. It is designed to be
  30      * augmented on to a host class, and provides the host with the ability to configure attributes to store and retrieve state,
  31      * along with attribute change events.
  32      * </p>
  33      * <p>For example, attributes added to the host can be configured:</p>
  34      * <ul>
  35      *     <li>As read only.</li>
  36      *     <li>As write once.</li>
  37      *     <li>With a setter function, which can be used to manipulate
  38      *     values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>
  39      *     <li>With a getter function, which can be used to manipulate stored values,
  40      *     before they are returned by Attribute's <a href="#method_get">get</a> method.</li>
  41      *     <li>With a validator function, to validate values before they are stored.</li>
  42      * </ul>
  43      *
  44      * <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration
  45      * options available for attributes.</p>
  46      *
  47      * <p><strong>NOTE:</strong> Most implementations will be better off extending the <a href="Base.html">Base</a> class,
  48      * instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration
  49      * of attributes for derived classes, accounting for values passed into the constructor.</p>
  50      *
  51      * @class Attribute
  52      * @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.
  53      * @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.
  54      * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
  55      * @uses AttributeCore
  56      * @uses AttributeEvents
  57      * @uses EventTarget
  58      * @uses AttributeExtras
  59      */
  60     var Attribute = function() {
  61
  62         // Fix #2531929
  63         // Complete hack, to make sure the first clone of a node value in IE doesn't doesn't hurt state - maintains 3.4.1 behavior.
  64         // Too late in the release cycle to do anything about the core problem.
  65         // The root issue is that cloning a Y.Node instance results in an object which barfs in IE, when you access it's properties (since 3.3.0).
  66         this._ATTR_E_FACADE = null;
  67         this._yuievt = null;
  68
  69         Y.AttributeCore.apply(this, arguments);
  70         Y.AttributeEvents.apply(this, arguments);
  71         Y.AttributeExtras.apply(this, arguments);
  72     };
  73
  74     Y.mix(Attribute, Y.AttributeCore, false, null, 1);
  75     Y.mix(Attribute, Y.AttributeExtras, false, null, 1);
  76
  77     // Needs to be "true", to overwrite methods from AttributeCore
  78     Y.mix(Attribute, Y.AttributeEvents, true, null, 1);
  79
  80     /**
  81      * <p>The value to return from an attribute setter in order to prevent the set from going through.</p>
  82      *
  83      * <p>You can return this value from your setter if you wish to combine validator and setter
  84      * functionality into a single setter function, which either returns the massaged value to be stored or
  85      * AttributeCore.INVALID_VALUE to prevent invalid values from being stored.</p>
  86      *
  87      * @property INVALID_VALUE
  88      * @type Object
  89      * @static
  90      * @final
  91      */
  92     Attribute.INVALID_VALUE = Y.AttributeCore.INVALID_VALUE;
  93
  94     /**
  95      * The list of properties which can be configured for
  96      * each attribute (e.g. setter, getter, writeOnce etc.).
  97      *
  98      * This property is used internally as a whitelist for faster
  99      * Y.mix operations.
 100      *
 101      * @property _ATTR_CFG
 102      * @type Array
 103      * @static
 104      * @protected
 105      */
 106     Attribute._ATTR_CFG = Y.AttributeCore._ATTR_CFG.concat(Y.AttributeEvents._ATTR_CFG);
 107
 108     Y.Attribute = Attribute;
 109
 110
 111 }, '3.5.1' ,{requires:['attribute-core', 'attribute-events', 'attribute-extras']});