base/js/BaseBuild.js

	BaseBuild.js revision 9f74fe13660a0d9d411c97798c85863de1745bbf
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental    /**
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     * The base-build submodule provides Base.build functionality, which
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     * can be used to create custom classes, by aggregating extensions onto
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     * a main class.
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     *
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     * @module base
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     * @submodule base-build
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     * @for Base
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental     */
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental    var Base = Y.Base,
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        L = Y.Lang,
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        INITIALIZER = "initializer",
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        DESTRUCTOR = "destructor",
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        build;
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental    Base._build = function(name, main, extensions, px, sx, cfg) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        var build = Base._build,
9d2da14dec9f62765544a573f9151d83b85d0909mental
9d2da14dec9f62765544a573f9151d83b85d0909mental            builtClass = build._ctor(main, cfg),
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            buildCfg = build._cfg(main, cfg),
648401434273d7165b6346f9d04675b138464d2fKris
ad83b521a557c8a2d91c469f74137ca4ff4ab2d1mental            _mixCust = build._mixCust,
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            extCfg,
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            aggregates = buildCfg.aggregates,
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
648401434273d7165b6346f9d04675b138464d2fKris            dynamic = builtClass._yuibuild.dynamic,
648401434273d7165b6346f9d04675b138464d2fKris
648401434273d7165b6346f9d04675b138464d2fKris            i, l, val, extClass, extProto,
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            initializer,
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            destructor;
be6c4327fc304962b439fd503536678e029ad51dmental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        if (dynamic && aggregates) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            for (i = 0, l = aggregates.length; i < l; ++i) {
17eb9e57e1550f744916bf486947162aa523bddamental                val = aggregates[i];
17eb9e57e1550f744916bf486947162aa523bddamental                if (main.hasOwnProperty(val)) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental                    builtClass[val] = L.isArray(main[val]) ? [] : {};
9d2da14dec9f62765544a573f9151d83b85d0909mental                }
9d2da14dec9f62765544a573f9151d83b85d0909mental            }
9d2da14dec9f62765544a573f9151d83b85d0909mental        }
9d2da14dec9f62765544a573f9151d83b85d0909mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        // Augment/Aggregate
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        for (i = 0, l = extensions.length; i < l; i++) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            extClass = extensions[i];
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            extProto = extClass.prototype;
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
9982f495cde2750b1c6446bfb152af73ab981512Johan Engelen            initializer = extProto[INITIALIZER];
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            destructor = extProto[DESTRUCTOR];
17eb9e57e1550f744916bf486947162aa523bddamental            delete extProto[INITIALIZER];
ad83b521a557c8a2d91c469f74137ca4ff4ab2d1mental            delete extProto[DESTRUCTOR];
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            // Prototype, old non-displacing augment
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            Y.mix(builtClass, extClass, true, null, 1);
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
648401434273d7165b6346f9d04675b138464d2fKris            // Custom Statics
648401434273d7165b6346f9d04675b138464d2fKris            _mixCust(builtClass, extClass, buildCfg);
648401434273d7165b6346f9d04675b138464d2fKris
648401434273d7165b6346f9d04675b138464d2fKris            // Extension Statics
7079a43aa387066c2f67402d77dbe3db981b1054Ted Gould            extCfg = extClass._buildCfg;
7079a43aa387066c2f67402d77dbe3db981b1054Ted Gould            if (extCfg) {
ad83b521a557c8a2d91c469f74137ca4ff4ab2d1mental                _mixCust(builtClass, extClass, extCfg, true);
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            }
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            if (initializer) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental                extProto[INITIALIZER] = initializer;
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            }
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            if (destructor) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental                extProto[DESTRUCTOR] = destructor;
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            }
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            builtClass._yuibuild.exts.push(extClass);
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        }
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        if (px) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            Y.mix(builtClass.prototype, px, true);
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        }
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental        if (sx) {
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            Y.mix(builtClass, build._clean(sx, buildCfg), true);
526c8bf9bb41b582dc49f54ac192705de9e2edf2mental            _mixCust(builtClass, sx, buildCfg);
a4030d5ca449e7e384bc699cd249ee704faaeab0Chris Morgan        }

        builtClass.prototype.hasImpl = build._impl;

        if (dynamic) {
            builtClass.NAME = name;
            builtClass.prototype.constructor = builtClass;
        }

        return builtClass;
    };

    build = Base._build;

    Y.mix(build, {

        _mixCust: function(r, s, cfg, isExt) {

            var aggregates,
                custom,
                statics,
                val,
                i,
                j,
                l;

            if (cfg) {
                aggregates = cfg.aggregates;
                custom = cfg.custom;
                statics = cfg.statics;
            }

            if (statics) {
                Y.mix(r, s, true, statics === true ? null : statics);
            }

            if (aggregates) {

                if (isExt) {
                    for (i = 0, l = aggregates.length; i < l; ++i) {
                        val = aggregates[i];
                        if (s.hasOwnProperty(val) && !r.hasOwnProperty(val)) {
                            r[val] = L.isArray(s[val]) ? [] : {};
                        }
                    }
                }

                Y.aggregate(r, s, true, aggregates);
            }

            if (custom) {
                for (j in custom) {
                    if (custom.hasOwnProperty(j)) {
                        custom[j](j, r, s);
                    }
                }
            }

        },

        _tmpl: function(main) {

            function BuiltClass() {
                BuiltClass.superclass.constructor.apply(this, arguments);
            }
            Y.extend(BuiltClass, main);

            return BuiltClass;
        },

        _impl : function(extClass) {
            var classes = this._getClasses(), i, l, cls, exts, ll, j;
            for (i = 0, l = classes.length; i < l; i++) {
                cls = classes[i];
                if (cls._yuibuild) {
                    exts = cls._yuibuild.exts;
                    ll = exts.length;

                    for (j = 0; j < ll; j++) {
                        if (exts[j] === extClass) {
                            return true;
                        }
                    }
                }
            }
            return false;
        },

        _ctor : function(main, cfg) {

           var dynamic = (cfg && false === cfg.dynamic) ? false : true,
               builtClass = (dynamic) ? build._tmpl(main) : main,
               buildCfg = builtClass._yuibuild;

            if (!buildCfg) {
                buildCfg = builtClass._yuibuild = {};
            }

            buildCfg.id = buildCfg.id || null;
            buildCfg.exts = buildCfg.exts || [];
            buildCfg.dynamic = dynamic;

            return builtClass;
        },

        _cfg : function(main, cfg) {
            var aggr = [],
                cust = {},
                buildCfg,
                cfgAggr = (cfg && cfg.aggregates),
                cfgCustBuild = (cfg && cfg.custom),
                c = main;

            while (c && c.prototype) {
                buildCfg = c._buildCfg;
                if (buildCfg) {
                    if (buildCfg.aggregates) {
                        aggr = aggr.concat(buildCfg.aggregates);
                    }
                    if (buildCfg.custom) {
                        Y.mix(cust, buildCfg.custom, true);
                    }
                }
                c = c.superclass ? c.superclass.constructor : null;
            }

            if (cfgAggr) {
                aggr = aggr.concat(cfgAggr);
            }
            if (cfgCustBuild) {
                Y.mix(cust, cfg.cfgBuild, true);
            }

            return {
                aggregates: aggr,
                custom: cust
            };
        },

        _clean : function(sx, cfg) {
            var prop, i, l, sxclone = Y.merge(sx),
                aggregates = cfg.aggregates,
                custom = cfg.custom;

            for (prop in custom) {
                if (sxclone.hasOwnProperty(prop)) {
                    delete sxclone[prop];
                }
            }

            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 build
     * @deprecated Use the more convenient Base.create and Base.mix methods instead
     * @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 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.
     * @param {Object} px The set of prototype properties/methods to add to the built class.
     * @param {Object} sx The set of static properties/methods to add to 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 mix
     * @static
     * @param {Function} main The existing class into which the extensions should be mixed.  The class needs to be Base or a 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 _buildCfg
     * @type Object
     * @static
     * @final
     * @private
     */
    Base._buildCfg = {
        custom : {
            ATTRS : function(prop, r, s) {

                r.ATTRS = r.ATTRS || {};

                if (s.ATTRS) {

                    var sAttrs = s.ATTRS,
                        rAttrs = r.ATTRS,
                        a;

                    for (a in sAttrs) {
                        if (sAttrs.hasOwnProperty(a)) {
                            rAttrs[a] = rAttrs[a] || {};
                            Y.mix(rAttrs[a], sAttrs[a], true);
                        }
                    }
                }
            }
        },
        aggregates : ["_PLUG", "_UNPLUG"]
    };