+ * A base class which objects requiring attributes and custom event support can + * extend. Base also handles the chaining of initializer and destructor methods across + * the hierarchy as part of object construction and destruction. Additionally, attributes configured + * through the static ATTRS property for each class + * in the hierarchy will be initialized by Base. + *
+ * + *+ * The static NAME property of each class extending + * from Base will be used as the identifier for the class, and is used by Base to prefix + * all events fired by instances of that class. + *
+ * @class Base + * @constructor + * @uses Attribute + * @uses Plugin.Host + * + * @param {Object} config Object with configuration property name/value pairs + */ + function Base() { + + Attribute.call(this); + + // If Plugin.Host has been augmented [ through base-pluginhost ], setup it's + // initial state, but don't initialize Plugins yet. That's done after initialization. + var PluginHost = Y.Plugin && Y.Plugin.Host; + if (this._initPlugins && PluginHost) { + PluginHost.call(this); + } + + if (this._lazyAddAttrs !== false) { this._lazyAddAttrs = true; } + + this.init.apply(this, arguments); + } + + /** + * The list of properties which can be configured for + * each attribute (e.g. setter, getter, writeOnce, readOnly etc.) + * + * @property Base._ATTR_CFG + * @type Array + * @static + * @private + */ + Base._ATTR_CFG = Attribute._ATTR_CFG.concat("cloneDefaultValue"); + + /** + *+ * The string to be used to identify instances of + * this class, for example in prefixing events. + *
+ *+ * Classes extending Base, should define their own + * static NAME property, which should be camelCase by + * convention (e.g. MyClass.NAME = "myClass";). + *
+ * @property Base.NAME + * @type String + * @static + */ + Base.NAME = "base"; + + /** + * The default set of attributes which will be available for instances of this class, and + * their configuration. In addition to the configuration properties listed by + * Attribute's addAttr method, the attribute + * can also be configured with a "cloneDefaultValue" property, which defines how the statically + * defined value field should be protected ("shallow", "deep" and false are supported values). + * + * By default if the value is an object literal or an array it will be "shallow" cloned, to + * protect the default value. + * + * @property Base.ATTRS + * @type Object + * @static + */ + Base.ATTRS = { + /** + * Flag indicating whether or not this object + * has been through the init lifecycle phase. + * + * @attribute initialized + * @readonly + * @default false + * @type boolean + */ + initialized: { + readOnly:true, + value:false + }, + + /** + * Flag indicating whether or not this object + * has been through the destroy lifecycle phase. + * + * @attribute destroyed + * @readonly + * @default false + * @type boolean + */ + destroyed: { + readOnly:true, + value:false + } + }; + + Base.prototype = { + + /** + * Init lifecycle method, invoked during construction. + * Fires the init event prior to setting up attributes and + * invoking initializers for the class hierarchy. + * + * @method init + * @final + * @chainable + * @param {Object} config Object with configuration property name/value pairs + * @return {Base} A reference to this object + */ + init: function(config) { + + /** + * The string used to identify the class of this object. + * + * @deprecated Use this.constructor.NAME + * @property name + * @type String + */ + this._yuievt.config.prefix = this.name = this.constructor.NAME; + + /** + *+ * Lifecycle event for the init phase, fired prior to initialization. + * Invoking the preventDefault() method on the event object provided + * to subscribers will prevent initialization from occuring. + *
+ *+ * Subscribers to the "after" momemt of this event, will be notified + * after initialization of the object is complete (and therefore + * cannot prevent initialization). + *
+ * + * @event init + * @preventable _defInitFn + * @param {EventFacade} e Event object, with a cfg property which + * refers to the configuration object passed to the constructor. + */ + this.publish(INIT, { + queuable:false, + defaultFn:this._defInitFn + }); + + if (config) { + if (config.on) { + this.on(config.on); + } + if (config.after) { + this.after(config.after); + } + } + + this.fire(INIT, {cfg: config}); + + return this; + }, + + /** + *+ * Destroy lifecycle method. Fires the destroy + * event, prior to invoking destructors for the + * class hierarchy. + *
+ *+ * Subscribers to the destroy + * event can invoke preventDefault on the event object, to prevent destruction + * from proceeding. + *
+ * @method destroy + * @return {Base} A reference to this object + * @final + * @chainable + */ + destroy: function() { + + /** + *+ * Lifecycle event for the destroy phase, + * fired prior to destruction. Invoking the preventDefault + * method on the event object provided to subscribers will + * prevent destruction from proceeding. + *
+ *+ * Subscribers to the "after" moment of this event, will be notified + * after destruction is complete (and as a result cannot prevent + * destruction). + *
+ * @event destroy + * @preventable _defDestroyFn + * @param {EventFacade} e Event object + */ + this.publish(DESTROY, { + queuable:false, + defaultFn: this._defDestroyFn + }); + this.fire(DESTROY); + return this; + }, + + /** + * Default init event handler + * + * @method _defInitFn + * @param {EventFacade} e Event object, with a cfg property which + * refers to the configuration object passed to the constructor. + * @protected + */ + _defInitFn : function(e) { + this._initHierarchy(e.cfg); + if (this._initPlugins) { + // Need to initPlugins manually, to handle constructor parsing, static Plug parsing + this._initPlugins(e.cfg); + } + this._set(INITIALIZED, true); + }, + + /** + * Default destroy event handler + * + * @method _defDestroyFn + * @param {EventFacade} e Event object + * @protected + */ + _defDestroyFn : function(e) { + this._destroyHierarchy(); + if (this._destroyPlugins) { + this._destroyPlugins(); + } + this._set(DESTROYED, true); + }, + + /** + * Returns the class hierarchy for this object, with Base being the last class in the array. + * + * @method _getClasses + * @protected + * @return {Function[]} An array of classes (constructor functions), making up the class hierarchy for this object. + * This value is cached the first time the method, or _getAttrCfgs, is invoked. Subsequent invocations return the + * cached value. + */ + _getClasses : function() { + if (!this._classes) { + this._initHierarchyData(); + } + return this._classes; + }, + + /** + * Returns an aggregated set of attribute configurations, by traversing the class hierarchy. + * + * @method _getAttrCfgs + * @protected + * @return {Object} The hash of attribute configurations, aggregated across classes in the hierarchy + * This value is cached the first time the method, or _getClasses, is invoked. Subsequent invocations return + * the cached value. + */ + _getAttrCfgs : function() { + if (!this._attrs) { + this._initHierarchyData(); + } + return this._attrs; + }, + + /** + * A helper method used when processing ATTRS across the class hierarchy during + * initialization. Returns a disposable object with the attributes defined for + * the provided class, extracted from the set of all attributes passed in . + * + * @method _filterAttrCfs + * @private + * + * @param {Function} clazz The class for which the desired attributes are required. + * @param {Object} allCfgs The set of all attribute configurations for this instance. + * Attributes will be removed from this set, if they belong to the filtered class, so + * that by the time all classes are processed, allCfgs will be empty. + * + * @return {Object} The set of attributes belonging to the class passed in, in the form + * of an object with attribute name/configuration pairs. + */ + _filterAttrCfgs : function(clazz, allCfgs) { + var cfgs = null, attr, attrs = clazz.ATTRS; + + if (attrs) { + for (attr in attrs) { + if (attrs.hasOwnProperty(attr) && allCfgs[attr]) { + cfgs = cfgs || {}; + cfgs[attr] = allCfgs[attr]; + delete allCfgs[attr]; + } + } + } + + return cfgs; + }, + + /** + * A helper method used by _getClasses and _getAttrCfgs, which determines both + * the array of classes and aggregate set of attribute configurations + * across the class hierarchy for the instance. + * + * @method _initHierarchyData + * @private + */ + _initHierarchyData : function() { + var c = this.constructor, + classes = [], + attrs = []; + + while (c) { + // Add to classes + classes[classes.length] = c; + + // Add to attributes + if (c.ATTRS) { + attrs[attrs.length] = c.ATTRS; + } + c = c.superclass ? c.superclass.constructor : null; + } + + this._classes = classes; + this._attrs = this._aggregateAttrs(attrs); + }, + + /** + * A helper method, used by _initHierarchyData to aggregate + * attribute configuration across the instances class hierarchy. + * + * The method will potect the attribute configuration value to protect the statically defined + * default value in ATTRS if required (if the value is an object literal, array or the + * attribute configuration has cloneDefaultValue set to shallow or deep). + * + * @method _aggregateAttrs + * @private + * @param {Array} allAttrs An array of ATTRS definitions across classes in the hierarchy + * (subclass first, Base last) + * @return {Object} The aggregate set of ATTRS definitions for the instance + */ + _aggregateAttrs : function(allAttrs) { + var attr, + attrs, + cfg, + val, + path, + i, + clone, + cfgProps = Base._ATTR_CFG, + aggAttrs = {}; + + if (allAttrs) { + for (i = allAttrs.length-1; i >= 0; --i) { + attrs = allAttrs[i]; + + for (attr in attrs) { + if (attrs.hasOwnProperty(attr)) { + + // Protect config passed in + cfg = Y.mix({}, attrs[attr], true, cfgProps); + + val = cfg.value; + clone = cfg.cloneDefaultValue; + + if (val) { + if ( (clone === undefined && (OBJECT_CONSTRUCTOR === val.constructor || L.isArray(val))) || clone === DEEP || clone === true) { + cfg.value = Y.clone(val); + } else if (clone === SHALLOW) { + cfg.value = Y.merge(val); + } + // else if (clone === false), don't clone the static default value. + // It's intended to be used by reference. + } + + path = null; + if (attr.indexOf(DOT) !== -1) { + path = attr.split(DOT); + attr = path.shift(); + } + + if (path && aggAttrs[attr] && aggAttrs[attr].value) { + O.setValue(aggAttrs[attr].value, path, val); + } else if (!path){ + if (!aggAttrs[attr]) { + aggAttrs[attr] = cfg; + } else { + Y.mix(aggAttrs[attr], cfg, true, cfgProps); + } + } + } + } + } + } + + return aggAttrs; + }, + + /** + * Initializes the class hierarchy for the instance, which includes + * initializing attributes for each class defined in the class's + * static ATTRS property and + * invoking the initializer method on the prototype of each class in the hierarchy. + * + * @method _initHierarchy + * @param {Object} userVals Object with configuration property name/value pairs + * @private + */ + _initHierarchy : function(userVals) { + var lazy = this._lazyAddAttrs, + constr, + constrProto, + ci, + ei, + el, + classes = this._getClasses(), + attrCfgs = this._getAttrCfgs(); + + for (ci = classes.length-1; ci >= 0; ci--) { + + constr = classes[ci]; + constrProto = constr.prototype; + + if (constr._yuibuild && constr._yuibuild.exts && !constr._yuibuild.dynamic) { + for (ei = 0, el = constr._yuibuild.exts.length; ei < el; ei++) { + constr._yuibuild.exts[ei].apply(this, arguments); + } + } + + this.addAttrs(this._filterAttrCfgs(constr, attrCfgs), userVals, lazy); + + if (constrProto.hasOwnProperty(INITIALIZER)) { + constrProto.initializer.apply(this, arguments); + } + } + }, + + /** + * Destroys the class hierarchy for this instance by invoking + * the descructor method on the prototype of each class in the hierarchy. + * + * @method _destroyHierarchy + * @private + */ + _destroyHierarchy : function() { + var constr, + constrProto, + ci, cl, + classes = this._getClasses(); + + for (ci = 0, cl = classes.length; ci < cl; ci++) { + constr = classes[ci]; + constrProto = constr.prototype; + if (constrProto.hasOwnProperty(DESTRUCTOR)) { + constrProto.destructor.apply(this, arguments); + } + } + }, + + /** + * Default toString implementation. Provides the constructor NAME + * and the instance ID. + * + * @method toString + * @return {String} String representation for this object + */ + toString: function() { + return this.constructor.NAME + "[" + Y.stamp(this) + "]"; + } + }; + + // Straightup augment, no wrapper functions + Y.mix(Base, Attribute, false, null, 1); + + // Fix constructor + Base.prototype.constructor = Base; + + Y.Base = Base; + + // Fix constructor + Base.prototype.constructor = Base; + + +}, '3.0.0' ,{requires:['attribute-base']});