base/js/BaseBuild.js

	BaseBuild.js revision 969d790cf689400dd37fcf1f11c1909a66c06de9
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass    /**
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * The base-build submodule provides Base.build functionality, which
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * can be used to create custom classes, by aggregating extensions onto
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * a main class.
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     *
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * @module base
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * @submodule base-build
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * @for Base
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     */
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass    var Base = Y.Base,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        L = Y.Lang,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        build;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass    Base._build = function(name, main, extensions, px, sx, cfg) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        var build = Base._build,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            builtClass = build._ctor(main, cfg),
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            buildCfg = build._cfg(main, cfg),
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            _mixCust = build._mixCust,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            aggregates = buildCfg.aggregates,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            custom = buildCfg.custom,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            dynamic = builtClass._yuibuild.dynamic,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            i, l, val, extClass;
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass        if (dynamic && aggregates) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            for (i = 0, l = aggregates.length; i < l; ++i) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                val = aggregates[i];
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                if (main.hasOwnProperty(val)) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    builtClass[val] = L.isArray(main[val]) ? [] : {};
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        // Augment/Aggregate
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        for (i = 0, l = extensions.length; i < l; i++) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            extClass = extensions[i];
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            // Prototype, old non-displacing augment
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            Y.mix(builtClass, extClass, true, null, 1);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass             // Custom Statics
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            _mixCust(builtClass, extClass, aggregates, custom);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            builtClass._yuibuild.exts.push(extClass);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        if (px) {
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass            Y.mix(builtClass.prototype, px, true);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        }
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass        if (sx) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            Y.mix(builtClass, build._clean(sx, aggregates, custom), true);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            _mixCust(builtClass, sx, aggregates, custom);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass        builtClass.prototype.hasImpl = build._impl;
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass        if (dynamic) {
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass            builtClass.NAME = name;
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass            builtClass.prototype.constructor = builtClass;
5432371fbb6d790a76159481f0dd16e806812153Dav Glass        }
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
216633e2ad28e9568a902f3763c3bef052c5f908Dav Glass        return builtClass;
5432371fbb6d790a76159481f0dd16e806812153Dav Glass    };
216633e2ad28e9568a902f3763c3bef052c5f908Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass    build = Base._build;
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass    Y.mix(build, {
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass        _mixCust: function(r, s, aggregates, custom) {
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass            if (aggregates) {
5432371fbb6d790a76159481f0dd16e806812153Dav Glass                Y.aggregate(r, s, true, aggregates);
5432371fbb6d790a76159481f0dd16e806812153Dav Glass            }
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass            if (custom) {
5432371fbb6d790a76159481f0dd16e806812153Dav Glass                for (var j in custom) {
5432371fbb6d790a76159481f0dd16e806812153Dav Glass                    if (custom.hasOwnProperty(j)) {
5432371fbb6d790a76159481f0dd16e806812153Dav Glass                        custom[j](j, r, s);
5432371fbb6d790a76159481f0dd16e806812153Dav Glass                    }
5432371fbb6d790a76159481f0dd16e806812153Dav Glass                }
5432371fbb6d790a76159481f0dd16e806812153Dav Glass            }
5432371fbb6d790a76159481f0dd16e806812153Dav Glass        },
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass        _tmpl: function(main) {
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
5432371fbb6d790a76159481f0dd16e806812153Dav Glass            function BuiltClass() {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                BuiltClass.superclass.constructor.apply(this, arguments);
a923e831550eefa370be5b58c742675f8820f00cDav Glass            }
5432371fbb6d790a76159481f0dd16e806812153Dav Glass            Y.extend(BuiltClass, main);
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
0523d0a8daaa474f0214203f8cbb0bc4a88e2964Dav Glass            return BuiltClass;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        },
5432371fbb6d790a76159481f0dd16e806812153Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        _impl : function(extClass) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            var classes = this._getClasses(), i, l, cls, exts, ll, j;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            for (i = 0, l = classes.length; i < l; i++) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                cls = classes[i];
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                if (cls._yuibuild) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    exts = cls._yuibuild.exts;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    ll = exts.length;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    for (j = 0; j < ll; j++) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                        if (exts[j] === extClass) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                            return true;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                        }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            return false;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        },
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        _ctor : function(main, cfg) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass           var dynamic = (cfg && false === cfg.dynamic) ? false : true,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                builtClass = (dynamic) ? build._tmpl(main) : main;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            builtClass._yuibuild = {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                id: null,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                exts : [],
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                dynamic: dynamic
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            };
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            return builtClass;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        },
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        _cfg : function(main, cfg) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            var aggr = [],
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                cust = {},
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                buildCfg,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                cfgAggr = (cfg && cfg.aggregates),
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                cfgCustBuild = (cfg && cfg.custom),
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                c = main;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            while (c && c.prototype) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                buildCfg = c._buildCfg;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                if (buildCfg) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    if (buildCfg.aggregates) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                        aggr = aggr.concat(buildCfg.aggregates);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    if (buildCfg.custom) {
d0bccce76452becc96b65acaaa684aa6fabaf386Dav Glass                        Y.mix(cust, buildCfg.custom, true);
d0bccce76452becc96b65acaaa684aa6fabaf386Dav Glass                    }
d0bccce76452becc96b65acaaa684aa6fabaf386Dav Glass                }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                c = c.superclass ? c.superclass.constructor : null;
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d0bccce76452becc96b65acaaa684aa6fabaf386Dav Glass            if (cfgAggr) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                aggr = aggr.concat(cfgAggr);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            if (cfgCustBuild) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                Y.mix(cust, cfg.cfgBuild, true);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            }
d0bccce76452becc96b65acaaa684aa6fabaf386Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            return {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                aggregates: aggr,
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                custom: cust
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            };
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        },
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass        _clean : function(sx, aggregates, custom) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            var prop, i, l, sxclone = Y.merge(sx);
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            for (prop in custom) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                if (sxclone.hasOwnProperty(prop)) {
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                    delete sxclone[prop];
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass                }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass            }
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass
            for (i = 0, l = aggregates.length; i < l; i++) {
                prop = aggregates[i];
                if (sxclone.hasOwnProperty(prop)) {
                    delete sxclone[prop];
                }
            }

            return sxclone;
        }
    });

    /**
     * <p>
     * Builds a custom constructor function (class) from the
     * main function, and array of extension functions (classes)
     * provided. The NAME field for the constructor function is
     * defined by the first argument passed in.
     * </p>
     * <p>
     * The cfg object supports the following properties
     * </p>
     * <dl>
     *    <dt>dynamic &#60;boolean&#62;</dt>
     *    <dd>
     *    <p>If true (default), a completely new class
     *    is created which extends the main class, and acts as the
     *    host on which the extension classes are augmented.</p>
     *    <p>If false, the extensions classes are augmented directly to
     *    the main class, modifying the main class' prototype.</p>
     *    </dd>
     *    <dt>aggregates &#60;String[]&#62;</dt>
     *    <dd>An array of static property names, which will get aggregated
     *    on to the built class, in addition to the default properties build
     *    will always aggregate as defined by the main class' static _buildCfg
     *    property.
     *    </dd>
     * </dl>
     *
     * @method Base.build
     * @static
     * @param {Function} name The name of the new class. Used to defined the NAME property for the new class.
     * @param {Function} main The main class on which to base the built class
     * @param {Function[]} extensions The set of extension classes which will be
     * augmented/aggregated to the built class.
     * @param {Object} cfg Optional. Build configuration for the class (see description).
     * @return {Function} A custom class, created from the provided main and extension classes
     */
    Base.build = function(name, main, extensions, cfg) {
        return build(name, main, extensions, null, null, cfg);
    };

    /**
     * <p>Creates a new class (constructor function) which extends the base class passed in as the second argument,
     * and mixes in the array of extensions provided.</p>
     * <p>Prototype properties or methods can be added to the new class, using the px argument (similar to Y.extend).</p>
     * <p>Static properties or methods can be added to the new class, using the sx argument (similar to Y.extend).</p>
     * <p>
     *
     * </p>
     * @method Base.create
     * @static
     * @param {Function} name The name of the newly created class. Used to defined the NAME property for the new class.
     * @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).
     * @param {Function[]} extensions The list of extensions which will be mixed into the built class.
     * @return {Function} The newly created class.
     */
    Base.create = function(name, base, extensions, px, sx) {
        return build(name, base, extensions, px, sx);
    };

    /**
     * <p>Mixes in a list of extensions to an existing class.</p>
     * @method Base.mix
     * @static
     * @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)
     * @param {Function[]} extensions The set of extension classes which will mixed into the existing main class.
     * @return {Function} The modified main class, with extensions mixed in.
     */
    Base.mix = function(main, extensions) {
        return build(null, main, extensions, null, null, {dynamic:false});
    };

    /**
     * The build configuration for the Base class.
     *
     * Defines the static fields which need to be aggregated
     * when the Base class is used as the main class passed to
     * the <a href="#method_Base.build">Base.build</a> method.
     *
     * @property Base._buildCfg
     * @type Object
     * @static
     * @final
     * @private
     */
    Base._buildCfg = {
        custom : {
            ATTRS : function(prop, r, s) {
                r[prop] = r[prop] || {};
                if (s[prop]) {
                    Y.aggregate(r[prop], s[prop], true);
                }
            }
        },
        aggregates : ["_PLUG", "_UNPLUG"]
    };