[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('attribute-base', function (Y, NAME) {
   9  
  10      /**
  11       * The attribute module provides an augmentable Attribute implementation, which
  12       * adds configurable attributes and attribute change events to the class being
  13       * augmented. It also provides a State class, which is used internally by Attribute,
  14       * but can also be used independently to provide a name/property/value data structure to
  15       * store state.
  16       *
  17       * @module attribute
  18       */
  19  
  20      /**
  21       * The attribute-base submodule provides core attribute handling support, with everything
  22       * aside from complex attribute handling in the provider's constructor.
  23       *
  24       * @module attribute
  25       * @submodule attribute-base
  26       */
  27  
  28      /**
  29       * <p>
  30       * Attribute provides configurable attribute support along with attribute change events. It is designed to be
  31       * augmented on to a host class, and provides the host with the ability to configure attributes to store and retrieve state,
  32       * along with attribute change events.
  33       * </p>
  34       * <p>For example, attributes added to the host can be configured:</p>
  35       * <ul>
  36       *     <li>As read only.</li>
  37       *     <li>As write once.</li>
  38       *     <li>With a setter function, which can be used to manipulate
  39       *     values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>
  40       *     <li>With a getter function, which can be used to manipulate stored values,
  41       *     before they are returned by Attribute's <a href="#method_get">get</a> method.</li>
  42       *     <li>With a validator function, to validate values before they are stored.</li>
  43       * </ul>
  44       *
  45       * <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration
  46       * options available for attributes.</p>
  47       *
  48       * <p><strong>NOTE:</strong> Most implementations will be better off extending the <a href="Base.html">Base</a> class,
  49       * instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration
  50       * of attributes for derived classes, accounting for values passed into the constructor.</p>
  51       *
  52       * @class Attribute
  53       * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>).
  54       *        These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
  55       * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>).
  56       *        These are not merged/cloned. The caller is responsible for isolating user provided values if required.
  57       * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
  58       * @uses AttributeCore
  59       * @uses AttributeObservable
  60       * @uses EventTarget
  61       * @uses AttributeExtras
  62       */
  63      function Attribute() {
  64          Y.AttributeCore.apply(this, arguments);
  65          Y.AttributeObservable.apply(this, arguments);
  66          Y.AttributeExtras.apply(this, arguments);
  67      }
  68  
  69      Y.mix(Attribute, Y.AttributeCore, false, null, 1);
  70      Y.mix(Attribute, Y.AttributeExtras, false, null, 1);
  71  
  72      // Needs to be `true`, to overwrite methods from AttributeCore
  73      Y.mix(Attribute, Y.AttributeObservable, true, null, 1);
  74  
  75      /**
  76       * <p>The value to return from an attribute setter in order to prevent the set from going through.</p>
  77       *
  78       * <p>You can return this value from your setter if you wish to combine validator and setter
  79       * functionality into a single setter function, which either returns the massaged value to be stored or
  80       * AttributeCore.INVALID_VALUE to prevent invalid values from being stored.</p>
  81       *
  82       * @property INVALID_VALUE
  83       * @type Object
  84       * @static
  85       * @final
  86       */
  87      Attribute.INVALID_VALUE = Y.AttributeCore.INVALID_VALUE;
  88  
  89      /**
  90       * The list of properties which can be configured for
  91       * each attribute (e.g. setter, getter, writeOnce etc.).
  92       *
  93       * This property is used internally as a whitelist for faster
  94       * Y.mix operations.
  95       *
  96       * @property _ATTR_CFG
  97       * @type Array
  98       * @static
  99       * @protected
 100       */
 101      Attribute._ATTR_CFG = Y.AttributeCore._ATTR_CFG.concat(Y.AttributeObservable._ATTR_CFG);
 102  
 103      /**
 104       * Utility method to protect an attribute configuration hash, by merging the
 105       * entire object and the individual attr config objects.
 106       *
 107       * @method protectAttrs
 108       * @static
 109       * @param {Object} attrs A hash of attribute to configuration object pairs.
 110       * @return {Object} A protected version of the `attrs` argument.
 111       */
 112      Attribute.protectAttrs = Y.AttributeCore.protectAttrs;
 113  
 114      Y.Attribute = Attribute;
 115  
 116  
 117  }, '3.17.2', {"requires": ["attribute-core", "attribute-observable", "attribute-extras"]});