jssource/src_files/include/javascript/yui3/build/base/base-build.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('base-build', function(Y) {
   9
  10     /**
  11      * The base-build submodule provides Base.build functionality, which
  12      * can be used to create custom classes, by aggregating extensions onto
  13      * a main class.
  14      *
  15      * @module base
  16      * @submodule base-build
  17      * @for Base
  18      */
  19     var Base = Y.Base,
  20         L = Y.Lang,
  21         build;
  22
  23     Base._build = function(name, main, extensions, px, sx, cfg) {
  24
  25         var build = Base._build,
  26
  27             builtClass = build._ctor(main, cfg),
  28             buildCfg = build._cfg(main, cfg),
  29
  30             _mixCust = build._mixCust,
  31
  32             aggregates = buildCfg.aggregates,
  33             custom = buildCfg.custom,
  34
  35             dynamic = builtClass._yuibuild.dynamic,
  36
  37             i, l, val, extClass;
  38
  39         if (dynamic && aggregates) {
  40             for (i = 0, l = aggregates.length; i < l; ++i) {
  41                 val = aggregates[i];
  42                 if (main.hasOwnProperty(val)) {
  43                     builtClass[val] = L.isArray(main[val]) ? [] : {};
  44                 }
  45             }
  46         }
  47
  48         // Augment/Aggregate
  49         for (i = 0, l = extensions.length; i < l; i++) {
  50             extClass = extensions[i];
  51
  52             // Prototype, old non-displacing augment
  53             Y.mix(builtClass, extClass, true, null, 1);
  54              // Custom Statics
  55             _mixCust(builtClass, extClass, aggregates, custom);
  56
  57             builtClass._yuibuild.exts.push(extClass);
  58         }
  59
  60         if (px) {
  61             Y.mix(builtClass.prototype, px, true);
  62         }
  63
  64         if (sx) {
  65             Y.mix(builtClass, build._clean(sx, aggregates, custom), true);
  66             _mixCust(builtClass, sx, aggregates, custom);
  67         }
  68
  69         builtClass.prototype.hasImpl = build._impl;
  70
  71         if (dynamic) {
  72             builtClass.NAME = name;
  73             builtClass.prototype.constructor = builtClass;
  74         }
  75
  76         return builtClass;
  77     };
  78
  79     build = Base._build;
  80
  81     Y.mix(build, {
  82
  83         _mixCust: function(r, s, aggregates, custom) {
  84
  85             if (aggregates) {
  86                 Y.aggregate(r, s, true, aggregates);
  87             }
  88
  89             if (custom) {
  90                 for (var j in custom) {
  91                     if (custom.hasOwnProperty(j)) {
  92                         custom[j](j, r, s);
  93                     }
  94                 }
  95             }
  96         },
  97
  98         _tmpl: function(main) {
  99
 100             function BuiltClass() {
 101                 BuiltClass.superclass.constructor.apply(this, arguments);
 102             }
 103             Y.extend(BuiltClass, main);
 104
 105             return BuiltClass;
 106         },
 107
 108         _impl : function(extClass) {
 109             var classes = this._getClasses(), i, l, cls, exts, ll, j;
 110             for (i = 0, l = classes.length; i < l; i++) {
 111                 cls = classes[i];
 112                 if (cls._yuibuild) {
 113                     exts = cls._yuibuild.exts;
 114                     ll = exts.length;
 115
 116                     for (j = 0; j < ll; j++) {
 117                         if (exts[j] === extClass) {
 118                             return true;
 119                         }
 120                     }
 121                 }
 122             }
 123             return false;
 124         },
 125
 126         _ctor : function(main, cfg) {
 127
 128            var dynamic = (cfg && false === cfg.dynamic) ? false : true,
 129                builtClass = (dynamic) ? build._tmpl(main) : main,
 130                buildCfg = builtClass._yuibuild;
 131
 132             if (!buildCfg) {
 133                 buildCfg = builtClass._yuibuild = {};
 134             }
 135
 136             buildCfg.id = buildCfg.id || null;
 137             buildCfg.exts = buildCfg.exts || [];
 138             buildCfg.dynamic = dynamic;
 139
 140             return builtClass;
 141         },
 142
 143         _cfg : function(main, cfg) {
 144             var aggr = [],
 145                 cust = {},
 146                 buildCfg,
 147                 cfgAggr = (cfg && cfg.aggregates),
 148                 cfgCustBuild = (cfg && cfg.custom),
 149                 c = main;
 150
 151             while (c && c.prototype) {
 152                 buildCfg = c._buildCfg;
 153                 if (buildCfg) {
 154                     if (buildCfg.aggregates) {
 155                         aggr = aggr.concat(buildCfg.aggregates);
 156                     }
 157                     if (buildCfg.custom) {
 158                         Y.mix(cust, buildCfg.custom, true);
 159                     }
 160                 }
 161                 c = c.superclass ? c.superclass.constructor : null;
 162             }
 163
 164             if (cfgAggr) {
 165                 aggr = aggr.concat(cfgAggr);
 166             }
 167             if (cfgCustBuild) {
 168                 Y.mix(cust, cfg.cfgBuild, true);
 169             }
 170
 171             return {
 172                 aggregates: aggr,
 173                 custom: cust
 174             };
 175         },
 176
 177         _clean : function(sx, aggregates, custom) {
 178             var prop, i, l, sxclone = Y.merge(sx);
 179
 180             for (prop in custom) {
 181                 if (sxclone.hasOwnProperty(prop)) {
 182                     delete sxclone[prop];
 183                 }
 184             }
 185
 186             for (i = 0, l = aggregates.length; i < l; i++) {
 187                 prop = aggregates[i];
 188                 if (sxclone.hasOwnProperty(prop)) {
 189                     delete sxclone[prop];
 190                 }
 191             }
 192
 193             return sxclone;
 194         }
 195     });
 196
 197     /**
 198      * <p>
 199      * Builds a custom constructor function (class) from the
 200      * main function, and array of extension functions (classes)
 201      * provided. The NAME field for the constructor function is
 202      * defined by the first argument passed in.
 203      * </p>
 204      * <p>
 205      * The cfg object supports the following properties
 206      * </p>
 207      * <dl>
 208      *    <dt>dynamic &#60;boolean&#62;</dt>
 209      *    <dd>
 210      *    <p>If true (default), a completely new class
 211      *    is created which extends the main class, and acts as the
 212      *    host on which the extension classes are augmented.</p>
 213      *    <p>If false, the extensions classes are augmented directly to
 214      *    the main class, modifying the main class' prototype.</p>
 215      *    </dd>
 216      *    <dt>aggregates &#60;String[]&#62;</dt>
 217      *    <dd>An array of static property names, which will get aggregated
 218      *    on to the built class, in addition to the default properties build
 219      *    will always aggregate as defined by the main class' static _buildCfg
 220      *    property.
 221      *    </dd>
 222      * </dl>
 223      *
 224      * @method Base.build
 225      * @deprecated Use the more convenient Base.create and Base.mix methods instead
 226      * @static
 227      * @param {Function} name The name of the new class. Used to defined the NAME property for the new class.
 228      * @param {Function} main The main class on which to base the built class
 229      * @param {Function[]} extensions The set of extension classes which will be
 230      * augmented/aggregated to the built class.
 231      * @param {Object} cfg Optional. Build configuration for the class (see description).
 232      * @return {Function} A custom class, created from the provided main and extension classes
 233      */
 234     Base.build = function(name, main, extensions, cfg) {
 235         return build(name, main, extensions, null, null, cfg);
 236     };
 237
 238     /**
 239      * <p>Creates a new class (constructor function) which extends the base class passed in as the second argument,
 240      * and mixes in the array of extensions provided.</p>
 241      * <p>Prototype properties or methods can be added to the new class, using the px argument (similar to Y.extend).</p>
 242      * <p>Static properties or methods can be added to the new class, using the sx argument (similar to Y.extend).</p>
 243      * <p>
 244      *
 245      * </p>
 246      * @method Base.create
 247      * @static
 248      * @param {Function} name The name of the newly created class. Used to defined the NAME property for the new class.
 249      * @param {Function} main The base class which the new class should extend. This class needs to be Base or a class derived from base (e.g. Widget).
 250      * @param {Function[]} extensions The list of extensions which will be mixed into the built class.
 251      * @param {Object} px The set of prototype properties/methods to add to the built class.
 252      * @param {Object} sx The set of static properties/methods to add to the built class.
 253      * @return {Function} The newly created class.
 254      */
 255     Base.create = function(name, base, extensions, px, sx) {
 256         return build(name, base, extensions, px, sx);
 257     };
 258
 259     /**
 260      * <p>Mixes in a list of extensions to an existing class.</p>
 261      * @method Base.mix
 262      * @static
 263      * @param {Function} main The existing class into which the extensions should be mixed.  The class needs to be Base or class derived from base (e.g. Widget)
 264      * @param {Function[]} extensions The set of extension classes which will mixed into the existing main class.
 265      * @return {Function} The modified main class, with extensions mixed in.
 266      */
 267     Base.mix = function(main, extensions) {
 268         return build(null, main, extensions, null, null, {dynamic:false});
 269     };
 270
 271     /**
 272      * The build configuration for the Base class.
 273      *
 274      * Defines the static fields which need to be aggregated
 275      * when the Base class is used as the main class passed to
 276      * the <a href="#method_Base.build">Base.build</a> method.
 277      *
 278      * @property Base._buildCfg
 279      * @type Object
 280      * @static
 281      * @final
 282      * @private
 283      */
 284     Base._buildCfg = {
 285         custom : {
 286             ATTRS : function(prop, r, s) {
 287
 288                 r.ATTRS = r.ATTRS || {};
 289
 290                 if (s.ATTRS) {
 291
 292                     var sAttrs = s.ATTRS,
 293                         rAttrs = r.ATTRS,
 294                         a;
 295
 296                     for (a in sAttrs) {
 297                         if (sAttrs.hasOwnProperty(a)) {
 298                             rAttrs[a] = rAttrs[a] || {};
 299                             Y.mix(rAttrs[a], sAttrs[a], true);
 300                         }
 301                     }
 302                 }
 303             }
 304         },
 305         aggregates : ["_PLUG", "_UNPLUG"]
 306     };
 307
 308
 309 }, '3.3.0' ,{requires:['base-base']});