lib/yuilib/3.13.0/base-base/base-base.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('base-base', function (Y, NAME) {
   9
  10     /**
  11      * The base module provides the Base class, which objects requiring attribute and custom event support can extend.
  12      * The module also provides two ways to reuse code - It augments Base with the Plugin.Host interface which provides
  13      * plugin support and also provides the BaseCore.build method which provides a way to build custom classes using extensions.
  14      *
  15      * @module base
  16      */
  17
  18     /**
  19      * The base-base submodule provides the Base class without the Plugin support, provided by Plugin.Host,
  20      * and without the extension support provided by BaseCore.build.
  21      *
  22      * @module base
  23      * @submodule base-base
  24      */
  25
  26     var AttributeCore   = Y.AttributeCore,
  27         AttributeExtras = Y.AttributeExtras,
  28         BaseCore        = Y.BaseCore,
  29         BaseObservable  = Y.BaseObservable;
  30
  31     /**
  32      * <p>
  33      * A base class which objects requiring attributes and custom event support can
  34      * extend. Base also handles the chaining of initializer and destructor methods across
  35      * the hierarchy as part of object construction and destruction. Additionally, attributes configured
  36      * through the static <a href="#property_ATTRS">ATTRS</a> property for each class
  37      * in the hierarchy will be initialized by Base.
  38      * </p>
  39      *
  40      * <p>
  41      * **NOTE:** Prior to version 3.11.0, ATTRS would get added a class at a time. That is,
  42      * Base would loop through each class in the hierarchy, and add the class' ATTRS, and
  43      * then call it's initializer, and move on to the subclass' ATTRS and initializer. As of
  44      * 3.11.0, ATTRS from all classes in the hierarchy are added in one `addAttrs` call before
  45      * any initializers are called. This fixes subtle edge-case issues with subclass ATTRS overriding
  46      * superclass `setter`, `getter` or `valueFn` definitions and being unable to get/set attributes
  47      * defined by the subclass. This order of operation change may impact `setter`, `getter` or `valueFn`
  48      * code which expects a superclass' initializer to have run. This is expected to be rare, but to support
  49      * it, Base supports a `_preAddAttrs()`, method hook (same signature as `addAttrs`). Components can
  50      * implement this method on their prototype for edge cases which do require finer control over
  51      * the order in which attributes are added (see widget-htmlparser).
  52      * </p>
  53      *
  54      * <p>
  55      * The static <a href="#property_NAME">NAME</a> property of each class extending
  56      * from Base will be used as the identifier for the class, and is used by Base to prefix
  57      * all events fired by instances of that class.
  58      * </p>
  59      *
  60      * @class Base
  61      * @constructor
  62      * @uses BaseCore
  63      * @uses BaseObservable
  64      * @uses AttributeCore
  65      * @uses AttributeObservable
  66      * @uses AttributeExtras
  67      * @uses EventTarget
  68      *
  69      * @param {Object} config Object with configuration property name/value pairs. The object can be
  70      * used to provide default values for the objects published attributes.
  71      *
  72      * <p>
  73      * The config object can also contain the following non-attribute properties, providing a convenient
  74      * way to configure events listeners and plugins for the instance, as part of the constructor call:
  75      * </p>
  76      *
  77      * <dl>
  78      *   <dt>on</dt>
  79      *   <dd>An event name to listener function map, to register event listeners for the "on" moment of the event.
  80      *       A constructor convenience property for the <a href="Base.html#method_on">on</a> method.</dd>
  81      *   <dt>after</dt>
  82      *   <dd>An event name to listener function map, to register event listeners for the "after" moment of the event.
  83      *       A constructor convenience property for the <a href="Base.html#method_after">after</a> method.</dd>
  84      *   <dt>bubbleTargets</dt>
  85      *   <dd>An object, or array of objects, to register as bubble targets for bubbled events fired by this instance.
  86      *       A constructor convenience property for the <a href="EventTarget.html#method_addTarget">addTarget</a> method.</dd>
  87      *   <dt>plugins</dt>
  88      *   <dd>A plugin, or array of plugins to be plugged into the instance (see PluginHost's plug method for signature details).
  89      *       A constructor convenience property for the <a href="Plugin.Host.html#method_plug">plug</a> method.</dd>
  90      * </dl>
  91      */
  92     function Base() {
  93         BaseCore.apply(this, arguments);
  94         BaseObservable.apply(this, arguments);
  95         AttributeExtras.apply(this, arguments);
  96     }
  97
  98     /**
  99      * The list of properties which can be configured for
 100      * each attribute (e.g. setter, getter, writeOnce, readOnly etc.)
 101      *
 102      * @property _ATTR_CFG
 103      * @type Array
 104      * @static
 105      * @private
 106      */
 107     Base._ATTR_CFG = BaseCore._ATTR_CFG.concat(BaseObservable._ATTR_CFG);
 108
 109     /**
 110      * The array of non-attribute configuration properties supported by this class.
 111      *
 112      * `Base` supports "on", "after", "plugins" and "bubbleTargets" properties,
 113      * which are not set up as attributes.
 114      *
 115      * This property is primarily required so that when
 116      * <a href="#property__allowAdHocAttrs">`_allowAdHocAttrs`</a> is enabled by
 117      * a class, non-attribute configurations don't get added as ad-hoc attributes.
 118      *
 119      * @property _NON_ATTRS_CFG
 120      * @type Array
 121      * @static
 122      * @private
 123      */
 124     Base._NON_ATTRS_CFG = BaseCore._NON_ATTRS_CFG.concat(BaseObservable._NON_ATTRS_CFG);
 125
 126     /**
 127      * <p>
 128      * The string to be used to identify instances of
 129      * this class, for example in prefixing events.
 130      * </p>
 131      * <p>
 132      * Classes extending Base, should define their own
 133      * static NAME property, which should be camelCase by
 134      * convention (e.g. MyClass.NAME = "myClass";).
 135      * </p>
 136      * @property NAME
 137      * @type String
 138      * @static
 139      */
 140     Base.NAME = 'base';
 141
 142     /**
 143      * The default set of attributes which will be available for instances of this class, and
 144      * their configuration. In addition to the configuration properties listed by
 145      * Attribute's <a href="Attribute.html#method_addAttr">addAttr</a> method, the attribute
 146      * can also be configured with a "cloneDefaultValue" property, which defines how the statically
 147      * defined value field should be protected ("shallow", "deep" and false are supported values).
 148      *
 149      * By default if the value is an object literal or an array it will be "shallow" cloned, to
 150      * protect the default value.
 151      *
 152      * @property ATTRS
 153      * @type Object
 154      * @static
 155      */
 156     Base.ATTRS = AttributeCore.protectAttrs(BaseCore.ATTRS);
 157
 158     /**
 159     Provides a way to safely modify a `Y.Base` subclass' static `ATTRS` after
 160     the class has been defined or created.
 161
 162     Base-based classes cache information about the class hierarchy in order to
 163     efficiently create instances. This cache includes includes the aggregated
 164     `ATTRS` configs. If the static `ATTRS` configs need to be modified after the
 165     class has been defined or create, then use this method which will make sure
 166     to clear any cached data before making any modifications.
 167
 168     @method modifyAttrs
 169     @param {Function} [ctor] The constructor function whose `ATTRS` should be
 170         modified. If a `ctor` function is not specified, then `this` is assumed
 171         to be the constructor which hosts the `ATTRS`.
 172     @param {Object} configs The collection of `ATTRS` configs to mix with the
 173         existing attribute configurations.
 174     @static
 175     @since 3.10.0
 176     **/
 177     Base.modifyAttrs = BaseCore.modifyAttrs;
 178
 179     Y.mix(Base, BaseCore, false, null, 1);
 180     Y.mix(Base, AttributeExtras, false, null, 1);
 181
 182     // Needs to be `true`, to overwrite methods from `BaseCore`.
 183     Y.mix(Base, BaseObservable, true, null, 1);
 184
 185     // Fix constructor
 186     Base.prototype.constructor = Base;
 187
 188     Y.Base = Base;
 189
 190
 191 }, '3.13.0', {"requires": ["attribute-base", "base-core", "base-observable"]});