lib/yui/3.5.1/build/base-base/base-base-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('base-base', function(Y) {
   8
   9     /**
  10      * The base module provides the Base class, which objects requiring attribute and custom event support can extend.
  11      * The module also provides two ways to reuse code - It augments Base with the Plugin.Host interface which provides
  12      * plugin support and also provides the BaseCore.build method which provides a way to build custom classes using extensions.
  13      *
  14      * @module base
  15      */
  16
  17     /**
  18      * The base-base submodule provides the Base class without the Plugin support, provided by Plugin.Host,
  19      * and without the extension support provided by BaseCore.build.
  20      *
  21      * @module base
  22      * @submodule base-base
  23      */
  24
  25     /**
  26      * The base module provides the Base class, which objects requiring attribute and custom event support can extend.
  27      * The module also provides two ways to reuse code - It augments Base with the Plugin.Host interface which provides
  28      * plugin support and also provides the Base.build method which provides a way to build custom classes using extensions.
  29      *
  30      * @module base
  31      */
  32
  33     /**
  34      * The base-base submodule provides the Base class without the Plugin support, provided by Plugin.Host,
  35      * and without the extension support provided by Base.build.
  36      *
  37      * @module base
  38      * @submodule base-base
  39      */
  40     var L = Y.Lang,
  41
  42         DESTROY = "destroy",
  43         INIT = "init",
  44
  45         BUBBLETARGETS = "bubbleTargets",
  46         _BUBBLETARGETS = "_bubbleTargets",
  47
  48         BaseCore = Y.BaseCore,
  49         AttributeCore = Y.AttributeCore,
  50         Attribute = Y.Attribute;
  51
  52     /**
  53      * <p>
  54      * A base class which objects requiring attributes and custom event support can
  55      * extend. Base also handles the chaining of initializer and destructor methods across
  56      * the hierarchy as part of object construction and destruction. Additionally, attributes configured
  57      * through the static <a href="#property_Base.ATTRS">ATTRS</a> property for each class
  58      * in the hierarchy will be initialized by Base.
  59      * </p>
  60      *
  61      * <p>
  62      * The static <a href="#property_Base.NAME">NAME</a> property of each class extending
  63      * from Base will be used as the identifier for the class, and is used by Base to prefix
  64      * all events fired by instances of that class.
  65      * </p>
  66      *
  67      * @class Base
  68      * @constructor
  69      * @uses BaseCore
  70      * @uses Attribute
  71      * @uses AttributeCore
  72      * @uses AttributeEvents
  73      * @uses AttributeExtras
  74      * @uses EventTarget
  75      *
  76      * @param {Object} config Object with configuration property name/value pairs. The object can be
  77      * used to provide default values for the objects published attributes.
  78      *
  79      * <p>
  80      * The config object can also contain the following non-attribute properties, providing a convenient
  81      * way to configure events listeners and plugins for the instance, as part of the constructor call:
  82      * </p>
  83      *
  84      * <dl>
  85      *     <dt>on</dt>
  86      *     <dd>An event name to listener function map, to register event listeners for the "on" moment of the event. A constructor convenience property for the <a href="Base.html#method_on">on</a> method.</dd>
  87      *     <dt>after</dt>
  88      *     <dd>An event name to listener function map, to register event listeners for the "after" moment of the event. A constructor convenience property for the <a href="Base.html#method_after">after</a> method.</dd>
  89      *     <dt>bubbleTargets</dt>
  90      *     <dd>An object, or array of objects, to register as bubble targets for bubbled events fired by this instance. A constructor convenience property for the <a href="EventTarget.html#method_addTarget">addTarget</a> method.</dd>
  91      *     <dt>plugins</dt>
  92      *     <dd>A plugin, or array of plugins to be plugged into the instance (see PluginHost's plug method for signature details). A constructor convenience property for the <a href="Plugin.Host.html#method_plug">plug</a> method.</dd>
  93      * </dl>
  94      */
  95     function Base() {
  96         BaseCore.apply(this, arguments);
  97     }
  98
  99     /**
 100      * The list of properties which can be configured for
 101      * each attribute (e.g. setter, getter, writeOnce, readOnly etc.)
 102      *
 103      * @property _ATTR_CFG
 104      * @type Array
 105      * @static
 106      * @private
 107      */
 108     Base._ATTR_CFG = Attribute._ATTR_CFG.concat("cloneDefaultValue");
 109     Base._ATTR_CFG_HASH = Y.Array.hash(Base._ATTR_CFG);
 110
 111     /**
 112      * The array of non-attribute configuration properties supported by this class.
 113      *
 114      * `Base` supports "on", "after", "plugins" and "bubbleTargets" properties,
 115      * which are not set up as attributes.
 116      *
 117      * This property is primarily required so that when
 118      * <a href="#property__allowAdHocAttrs">`_allowAdHocAttrs`</a> is enabled by
 119      * a class, non-attribute configurations don't get added as ad-hoc attributes.
 120      *
 121      * @property _NON_ATTRS_CFG
 122      * @type Array
 123      * @static
 124      * @private
 125      */
 126     Base._NON_ATTRS_CFG = BaseCore._NON_ATTRS_CFG.concat(["on", "after", "bubbleTargets"]);
 127
 128     /**
 129      * <p>
 130      * The string to be used to identify instances of
 131      * this class, for example in prefixing events.
 132      * </p>
 133      * <p>
 134      * Classes extending Base, should define their own
 135      * static NAME property, which should be camelCase by
 136      * convention (e.g. MyClass.NAME = "myClass";).
 137      * </p>
 138      * @property NAME
 139      * @type String
 140      * @static
 141      */
 142     Base.NAME = "base";
 143
 144     /**
 145      * The default set of attributes which will be available for instances of this class, and
 146      * their configuration. In addition to the configuration properties listed by
 147      * Attribute's <a href="Attribute.html#method_addAttr">addAttr</a> method, the attribute
 148      * can also be configured with a "cloneDefaultValue" property, which defines how the statically
 149      * defined value field should be protected ("shallow", "deep" and false are supported values).
 150      *
 151      * By default if the value is an object literal or an array it will be "shallow" cloned, to
 152      * protect the default value.
 153      *
 154      * @property ATTRS
 155      * @type Object
 156      * @static
 157      */
 158     Base.ATTRS = AttributeCore.prototype._protectAttrs(BaseCore.ATTRS);
 159
 160     Base.prototype = {
 161
 162         /**
 163          * Internal construction logic for Base.
 164          *
 165          * @method _initBase
 166          * @param {Object} config The constructor configuration object
 167          * @private
 168          */
 169         _initBase: function(cfg) {
 170             Y.log('init called', 'life', 'base');
 171
 172             this._eventPrefix = this.constructor.EVENT_PREFIX || this.constructor.NAME;
 173
 174             Y.BaseCore.prototype._initBase.call(this, cfg);
 175         },
 176
 177         /**
 178          * Initializes Attribute
 179          *
 180          * @method _initAttribute
 181          * @private
 182          */
 183         _initAttribute: function(cfg) {
 184             Attribute.call(this);
 185             this._yuievt.config.prefix = this._eventPrefix;
 186         },
 187
 188         /**
 189          * Utility method to define the attribute hash used to filter/whitelist property mixes for
 190          * this class.
 191          *
 192          * @method _attrCfgHash
 193          * @private
 194          */
 195         _attrCfgHash: function() {
 196             return Base._ATTR_CFG_HASH;
 197         },
 198
 199         /**
 200          * Init lifecycle method, invoked during construction.
 201          * Fires the init event prior to setting up attributes and
 202          * invoking initializers for the class hierarchy.
 203          *
 204          * @method init
 205          * @chainable
 206          * @param {Object} config Object with configuration property name/value pairs
 207          * @return {Base} A reference to this object
 208          */
 209         init: function(config) {
 210             /**
 211              * <p>
 212              * Lifecycle event for the init phase, fired prior to initialization.
 213              * Invoking the preventDefault() method on the event object provided
 214              * to subscribers will prevent initialization from occuring.
 215              * </p>
 216              * <p>
 217              * Subscribers to the "after" momemt of this event, will be notified
 218              * after initialization of the object is complete (and therefore
 219              * cannot prevent initialization).
 220              * </p>
 221              *
 222              * @event init
 223              * @preventable _defInitFn
 224              * @param {EventFacade} e Event object, with a cfg property which
 225              * refers to the configuration object passed to the constructor.
 226              */
 227             this.publish(INIT, {
 228                 queuable:false,
 229                 fireOnce:true,
 230                 defaultTargetOnly:true,
 231                 defaultFn:this._defInitFn
 232             });
 233
 234             this._preInitEventCfg(config);
 235
 236             this.fire(INIT, {cfg: config});
 237
 238             return this;
 239         },
 240
 241         /**
 242          * Handles the special on, after and target properties which allow the user to
 243          * easily configure on and after listeners as well as bubble targets during
 244          * construction, prior to init.
 245          *
 246          * @private
 247          * @method _preInitEventCfg
 248          * @param {Object} config The user configuration object
 249          */
 250         _preInitEventCfg : function(config) {
 251             if (config) {
 252                 if (config.on) {
 253                     this.on(config.on);
 254                 }
 255                 if (config.after) {
 256                     this.after(config.after);
 257                 }
 258             }
 259
 260             var i, l, target,
 261                 userTargets = (config && BUBBLETARGETS in config);
 262
 263             if (userTargets || _BUBBLETARGETS in this) {
 264                 target = userTargets ? (config && config.bubbleTargets) : this._bubbleTargets;
 265                 if (L.isArray(target)) {
 266                     for (i = 0, l = target.length; i < l; i++) {
 267                         this.addTarget(target[i]);
 268                     }
 269                 } else if (target) {
 270                     this.addTarget(target);
 271                 }
 272             }
 273         },
 274
 275         /**
 276          * <p>
 277          * Destroy lifecycle method. Fires the destroy
 278          * event, prior to invoking destructors for the
 279          * class hierarchy.
 280          * </p>
 281          * <p>
 282          * Subscribers to the destroy
 283          * event can invoke preventDefault on the event object, to prevent destruction
 284          * from proceeding.
 285          * </p>
 286          * @method destroy
 287          * @return {Base} A reference to this object
 288          * @chainable
 289          */
 290         destroy: function() {
 291             Y.log('destroy called', 'life', 'base');
 292
 293             /**
 294              * <p>
 295              * Lifecycle event for the destroy phase,
 296              * fired prior to destruction. Invoking the preventDefault
 297              * method on the event object provided to subscribers will
 298              * prevent destruction from proceeding.
 299              * </p>
 300              * <p>
 301              * Subscribers to the "after" moment of this event, will be notified
 302              * after destruction is complete (and as a result cannot prevent
 303              * destruction).
 304              * </p>
 305              * @event destroy
 306              * @preventable _defDestroyFn
 307              * @param {EventFacade} e Event object
 308              */
 309             this.publish(DESTROY, {
 310                 queuable:false,
 311                 fireOnce:true,
 312                 defaultTargetOnly:true,
 313                 defaultFn: this._defDestroyFn
 314             });
 315             this.fire(DESTROY);
 316
 317             this.detachAll();
 318             return this;
 319         },
 320
 321         /**
 322          * Default init event handler
 323          *
 324          * @method _defInitFn
 325          * @param {EventFacade} e Event object, with a cfg property which
 326          * refers to the configuration object passed to the constructor.
 327          * @protected
 328          */
 329         _defInitFn : function(e) {
 330             this._baseInit(e.cfg);
 331         },
 332
 333         /**
 334          * Default destroy event handler
 335          *
 336          * @method _defDestroyFn
 337          * @param {EventFacade} e Event object
 338          * @protected
 339          */
 340         _defDestroyFn : function(e) {
 341             this._baseDestroy(e.cfg);
 342         }
 343     };
 344
 345     Y.mix(Base, Attribute, false, null, 1);
 346     Y.mix(Base, BaseCore, false, null, 1);
 347
 348     // Fix constructor
 349     Base.prototype.constructor = Base;
 350
 351     Y.Base = Base;
 352
 353
 354 }, '3.5.1' ,{requires:['base-core', 'attribute-base']});