3
Copyright 2012 Yahoo! Inc. All rights reserved.
4
Licensed under the BSD License.
5
http://yuilibrary.com/license/
7
YUI.add('base-build', function(Y) {
10
* The base-build submodule provides Base.build functionality, which
11
* can be used to create custom classes, by aggregating extensions onto
15
* @submodule base-build
20
INITIALIZER = "initializer",
21
DESTRUCTOR = "destructor",
23
arrayAggregator = function (prop, r, s) {
25
r[prop] = (r[prop] || []).concat(s[prop]);
29
Base._build = function(name, main, extensions, px, sx, cfg) {
31
var build = Base._build,
33
builtClass = build._ctor(main, cfg),
34
buildCfg = build._cfg(main, cfg, extensions),
36
_mixCust = build._mixCust,
38
dynamic = builtClass._yuibuild.dynamic,
40
i, l, extClass, extProto,
45
for (i = 0, l = extensions.length; i < l; i++) {
46
extClass = extensions[i];
48
extProto = extClass.prototype;
50
initializer = extProto[INITIALIZER];
51
destructor = extProto[DESTRUCTOR];
52
delete extProto[INITIALIZER];
53
delete extProto[DESTRUCTOR];
55
// Prototype, old non-displacing augment
56
Y.mix(builtClass, extClass, true, null, 1);
59
_mixCust(builtClass, extClass, buildCfg);
62
extProto[INITIALIZER] = initializer;
66
extProto[DESTRUCTOR] = destructor;
69
builtClass._yuibuild.exts.push(extClass);
73
Y.mix(builtClass.prototype, px, true);
77
Y.mix(builtClass, build._clean(sx, buildCfg), true);
78
_mixCust(builtClass, sx, buildCfg);
81
builtClass.prototype.hasImpl = build._impl;
84
builtClass.NAME = name;
85
builtClass.prototype.constructor = builtClass;
95
_mixCust: function(r, s, cfg) {
105
aggregates = cfg.aggregates;
107
statics = cfg.statics;
111
Y.mix(r, s, true, statics);
115
for (i = 0, l = aggregates.length; i < l; i++) {
116
aggr = aggregates[i];
117
if (!r.hasOwnProperty(aggr) && s.hasOwnProperty(aggr)) {
118
r[aggr] = L.isArray(s[aggr]) ? [] : {};
120
Y.aggregate(r, s, true, [aggr]);
126
if (custom.hasOwnProperty(i)) {
134
_tmpl: function(main) {
136
function BuiltClass() {
137
BuiltClass.superclass.constructor.apply(this, arguments);
139
Y.extend(BuiltClass, main);
144
_impl : function(extClass) {
145
var classes = this._getClasses(), i, l, cls, exts, ll, j;
146
for (i = 0, l = classes.length; i < l; i++) {
149
exts = cls._yuibuild.exts;
152
for (j = 0; j < ll; j++) {
153
if (exts[j] === extClass) {
162
_ctor : function(main, cfg) {
164
var dynamic = (cfg && false === cfg.dynamic) ? false : true,
165
builtClass = (dynamic) ? build._tmpl(main) : main,
166
buildCfg = builtClass._yuibuild;
169
buildCfg = builtClass._yuibuild = {};
172
buildCfg.id = buildCfg.id || null;
173
buildCfg.exts = buildCfg.exts || [];
174
buildCfg.dynamic = dynamic;
179
_cfg : function(main, cfg, exts) {
184
cfgAggr = (cfg && cfg.aggregates),
185
cfgCustBuild = (cfg && cfg.custom),
186
cfgStatics = (cfg && cfg.statics),
192
while (c && c.prototype) {
193
buildCfg = c._buildCfg;
195
if (buildCfg.aggregates) {
196
aggr = aggr.concat(buildCfg.aggregates);
198
if (buildCfg.custom) {
199
Y.mix(cust, buildCfg.custom, true);
201
if (buildCfg.statics) {
202
statics = statics.concat(buildCfg.statics);
205
c = c.superclass ? c.superclass.constructor : null;
210
for (i = 0, l = exts.length; i < l; i++) {
212
buildCfg = c._buildCfg;
214
if (buildCfg.aggregates) {
215
aggr = aggr.concat(buildCfg.aggregates);
217
if (buildCfg.custom) {
218
Y.mix(cust, buildCfg.custom, true);
220
if (buildCfg.statics) {
221
statics = statics.concat(buildCfg.statics);
228
aggr = aggr.concat(cfgAggr);
232
Y.mix(cust, cfg.cfgBuild, true);
236
statics = statics.concat(cfgStatics);
246
_clean : function(sx, cfg) {
247
var prop, i, l, sxclone = Y.merge(sx),
248
aggregates = cfg.aggregates,
251
for (prop in custom) {
252
if (sxclone.hasOwnProperty(prop)) {
253
delete sxclone[prop];
257
for (i = 0, l = aggregates.length; i < l; i++) {
258
prop = aggregates[i];
259
if (sxclone.hasOwnProperty(prop)) {
260
delete sxclone[prop];
270
* Builds a custom constructor function (class) from the
271
* main function, and array of extension functions (classes)
272
* provided. The NAME field for the constructor function is
273
* defined by the first argument passed in.
276
* The cfg object supports the following properties
279
* <dt>dynamic <boolean></dt>
281
* <p>If true (default), a completely new class
282
* is created which extends the main class, and acts as the
283
* host on which the extension classes are augmented.</p>
284
* <p>If false, the extensions classes are augmented directly to
285
* the main class, modifying the main class' prototype.</p>
287
* <dt>aggregates <String[]></dt>
288
* <dd>An array of static property names, which will get aggregated
289
* on to the built class, in addition to the default properties build
290
* will always aggregate as defined by the main class' static _buildCfg
296
* @deprecated Use the more convenient Base.create and Base.mix methods instead
298
* @param {Function} name The name of the new class. Used to defined the NAME property for the new class.
299
* @param {Function} main The main class on which to base the built class
300
* @param {Function[]} extensions The set of extension classes which will be
301
* augmented/aggregated to the built class.
302
* @param {Object} cfg Optional. Build configuration for the class (see description).
303
* @return {Function} A custom class, created from the provided main and extension classes
305
Base.build = function(name, main, extensions, cfg) {
306
return build(name, main, extensions, null, null, cfg);
310
* Creates a new class (constructor function) which extends the base class passed in as the second argument,
311
* and mixes in the array of extensions provided.
313
* Prototype properties or methods can be added to the new class, using the px argument (similar to Y.extend).
315
* Static properties or methods can be added to the new class, using the sx argument (similar to Y.extend).
317
* **NOTE FOR COMPONENT DEVELOPERS**: Both the `base` class, and `extensions` can define static a `_buildCfg`
318
* property, which acts as class creation meta-data, and drives how special static properties from the base
319
* class, or extensions should be copied, aggregated or (custom) mixed into the newly created class.
321
* The `_buildCfg` property is a hash with 3 supported properties: `statics`, `aggregates` and `custom`, e.g:
323
* // If the Base/Main class is the thing introducing the property:
325
* MyBaseClass._buildCfg = {
327
* // Static properties/methods to copy (Alias) to the built class.
328
* statics: ["CopyThisMethod", "CopyThisProperty"],
330
* // Static props to aggregate onto the built class.
331
* aggregates: ["AggregateThisProperty"],
333
* // Static properties which need custom handling (e.g. deep merge etc.)
335
* "CustomProperty" : function(property, Receiver, Supplier) {
337
* var triggers = Receiver.CustomProperty.triggers;
338
Receiver.CustomProperty.triggers = triggers.concat(Supplier.CustomProperty.triggers);
344
* MyBaseClass.CopyThisMethod = function() {...};
345
* MyBaseClass.CopyThisProperty = "foo";
346
* MyBaseClass.AggregateThisProperty = {...};
347
* MyBaseClass.CustomProperty = {
351
* // Or, if the Extension is the thing introducing the property:
353
* MyExtension._buildCfg = {
359
* This way, when users pass your base or extension class to `Y.Base.create` or `Y.Base.mix`, they don't need to
360
* know which properties need special handling. `Y.Base` has a buildCfg which defines `ATTRS` for custom mix handling
361
* (to protect the static config objects), and `Y.Widget` has a buildCfg which specifies `HTML_PARSER` for
362
* straight up aggregation.
366
* @param {Function} name The name of the newly created class. Used to defined the NAME property for the new class.
367
* @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).
368
* @param {Function[]} extensions The list of extensions which will be mixed into the built class.
369
* @param {Object} px The set of prototype properties/methods to add to the built class.
370
* @param {Object} sx The set of static properties/methods to add to the built class.
371
* @return {Function} The newly created class.
373
Base.create = function(name, base, extensions, px, sx) {
374
return build(name, base, extensions, px, sx);
378
* <p>Mixes in a list of extensions to an existing class.</p>
381
* @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)
382
* @param {Function[]} extensions The set of extension classes which will mixed into the existing main class.
383
* @return {Function} The modified main class, with extensions mixed in.
385
Base.mix = function(main, extensions) {
386
return build(null, main, extensions, null, null, {dynamic:false});
390
* The build configuration for the Base class.
392
* Defines the static fields which need to be aggregated
393
* when the Base class is used as the main class passed to
394
* the <a href="#method_Base.build">Base.build</a> method.
396
* @property _buildCfg
404
ATTRS : function(prop, r, s) {
406
r.ATTRS = r.ATTRS || {};
410
var sAttrs = s.ATTRS,
415
if (sAttrs.hasOwnProperty(a)) {
416
rAttrs[a] = rAttrs[a] || {};
417
Y.mix(rAttrs[a], sAttrs[a], true);
422
_NON_ATTRS_CFG : arrayAggregator
424
aggregates : ["_PLUG", "_UNPLUG"]
428
}, '3.5.0' ,{requires:['base-base']});