Base.js revision eaa9719567e2ec55d96f9298077f5fc0effe1ed3
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The base module provides the Base class, which objects requiring attribute and custom event support can extend.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The module also provides two ways to reuse code - An augmentable Plugin.Host interface which provides plugin support
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * (which is augmented to the Base class) and Base.build which provides a way to
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * build custom classes using extensions.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @module base
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The base-base submodule provides the Base class and augmentable Plugin.Host implementation,
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * without the extension support provided by Base.build.
09ab44e129e6795eed34adfc06f7b741034e88a4Dav Glass * @module base
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @submodule base-base
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren var O = Y.Object,
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren OBJECT_CONSTRUCTOR = Object.prototype.constructor,
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * A base class which objects requiring attributes and custom event support can
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * extend. Base also handles the chaining of initializer and destructor methods across
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * the hierarchy as part of object construction and destruction. Additionally, attributes configured
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * through the static <a href="#property_Base.ATTRS">ATTRS</a> property for each class
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * in the hierarchy will be initialized by Base.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The static <a href="#property_Base.NAME">NAME</a> property of each class extending
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * from Base will be used as the identifier for the class, and is used by Base to prefix
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * all events fired by instances of that class.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @class Base
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @constructor
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @uses Attribute
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @uses Plugin.Host
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Object} config Object with configuration property name/value pairs
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren Y.log('constructor called', 'life', 'base');
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren this._silentInit = this._silentInit || false;
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren if (this._lazyAddAttrs !== false) { this._lazyAddAttrs = true; }
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The list of properties which can be configured for
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * each attribute (e.g. setter, getter, writeOnce, readOnly etc.)
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @property Base._ATTR_CFG
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @type Array
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren Base._ATTR_CFG = Y.Attribute._ATTR_CFG.concat("cloneDefaultValue");
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The string to be used to identify instances of
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * this class, for example in prefixing events.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Classes extending Base, should define their own
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * static NAME property, which should be camelCase by
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * convention (e.g. MyClass.NAME = "myClass";).
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @property Base.NAME
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @type String
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The default set of attributes which will be available for instances of this class, and
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * their configuration. In addition to the configuration properties listed by
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Attribute's <a href="Attribute.html#method_addAttr">addAttr</a> method, the attribute
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * can also be configured with a "cloneDefaultValue" property, which defines how the statically
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * defined value field should be protected ("shallow", "deep" and false are supported values).
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * By default if the value is an object literal or an array it will be "shallow" cloned, to
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * protect the default value.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @property Base.ATTRS
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @type Object
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Flag indicating whether or not this object
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * has been through the init lifecycle phase.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @attribute initialized
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @default false
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @type boolean
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Flag indicating whether or not this object
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * has been through the destroy lifecycle phase.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @attribute destroyed
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @default false
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @type boolean
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Init lifecycle method, invoked during construction.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Fires the init event prior to setting up attributes and
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * invoking initializers for the class hierarchy.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method init
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Object} config Object with configuration property name/value pairs
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @return {Base} A reference to this object
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The string used to identify the class of this object.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @deprecated Use this.constructor.NAME
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @property name
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @type String
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren this._yuievt.config.prefix = this.name = this.constructor.NAME;
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Lifecycle event for the init phase, fired prior to initialization.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Invoking the preventDefault() method on the event object provided
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * to subscribers will prevent initialization from occuring.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Subscribers to the "after" momemt of this event, will be notified
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * after initialization of the object is complete (and therefore
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * cannot prevent initialization).
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @event init
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @preventable _defInitFn
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Event.Facade} e Event object, with a cfg property which
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * refers to the configuration object passed to the constructor.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Destroy lifecycle method. Fires the destroy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * event, prior to invoking destructors for the
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * class hierarchy.
6b26605d416d593055b8fba4d274a80efc77a7b3Eduardo Lundgren * Subscribers to the destroy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * event can invoke preventDefault on the event object, to prevent destruction
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * from proceeding.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method destroy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @return {Base} A reference to this object
1733ad5823502d24c084b74ae60d838307d23dc0Eduardo Lundgren * Lifecycle event for the destroy phase,
1733ad5823502d24c084b74ae60d838307d23dc0Eduardo Lundgren * fired prior to destruction. Invoking the preventDefault
1733ad5823502d24c084b74ae60d838307d23dc0Eduardo Lundgren * method on the event object provided to subscribers will
1733ad5823502d24c084b74ae60d838307d23dc0Eduardo Lundgren * prevent destruction from proceeding.
1733ad5823502d24c084b74ae60d838307d23dc0Eduardo Lundgren * Subscribers to the "after" moment of this event, will be notified
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * after destruction is complete (and as a result cannot prevent
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * destruction).
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @event destroy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @preventable _defDestroyFn
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Event.Facade} e Event object
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Default init event handler
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _defInitFn
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Event.Facade} e Event object, with a cfg property which
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * refers to the configuration object passed to the constructor.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren _defInitFn : function(e) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Default destroy event handler
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _defDestroyFn
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Event.Facade} e Event object
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Returns the class hierarchy for this object, with Base being the last class in the array.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _getClasses
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @return {Function[]} An array of classes (constructor functions), making up the class hierarchy for this object.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * This value is cached the first time the method, or _getAttrCfgs, is invoked. Subsequent invocations return the
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * cached value.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Returns an aggregated set of attribute configurations, by traversing the class hierarchy.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _getAttrCfgs
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @return {Object} The hash of attribute configurations, aggregated across classes in the hierarchy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * This value is cached the first time the method, or _getClasses, is invoked. Subsequent invocations return
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * the cached value.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * A helper method used when processing ATTRS across the class hierarchy during
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * initialization. Returns a disposable object with the attributes defined for
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * the provided class, extracted from the set of all attributes passed in .
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _filterAttrCfs
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Function} clazz The class for which the desired attributes are required.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Object} allCfgs The set of all attribute configurations for this instance.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Attributes will be removed from this set, if they belong to the filtered class, so
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * that by the time all classes are processed, allCfgs will be empty.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @return {Object} The set of attributes belonging to the class passed in, in the form
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * of an object with attribute name/configuration pairs.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren _filterAttrCfgs : function(clazz, allCfgs) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren var cfgs = null, attr, attrs = clazz.ATTRS;
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren if (attrs.hasOwnProperty(attr) && allCfgs[attr]) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * A helper method used by _getClasses and _getAttrCfgs, which determines both
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * the array of classes and aggregate set of attribute configurations
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * across the class hierarchy for the instance.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _initHierarchyData
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren // Add to classes
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren // Add to attributes
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren c = c.superclass ? c.superclass.constructor : null;
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * A helper method, used by _initHierarchyData to aggregate
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * attribute configuration across the instances class hierarchy.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * The method will potect the attribute configuration value to protect the statically defined
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * default value in ATTRS if required (if the value is an object literal, array or the
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * attribute configuration has cloneDefaultValue set to shallow or deep).
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _aggregateAttrs
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Array} allAttrs An array of ATTRS definitions across classes in the hierarchy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * (subclass first, Base last)
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @return {Object} The aggregate set of ATTRS definitions for the instance
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren // Protect config passed in
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren cfg = Y.mix({}, attrs[attr], true, cfgProps);
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren if ( (clone === undefined && (OBJECT_CONSTRUCTOR === val.constructor || L.isArray(val))) || clone === DEEP || clone === true) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren Y.log('Cloning default value for attribute:' + attr, 'info', 'base');
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren Y.log('Merging default value for attribute:' + attr, 'info', 'base');
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren // else if (clone === false), don't clone the static default value.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren // It's intended to be used by reference.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren if (path && aggAttrs[attr] && aggAttrs[attr].value) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren O.setValue(aggAttrs[attr].value, path, val);
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren } else if (!path){
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren Y.mix(aggAttrs[attr], cfg, true, cfgProps);
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Initializes the class hierarchy for the instance, which includes
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * initializing attributes for each class defined in the class's
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * static <a href="#property_Base.ATTRS">ATTRS</a> property and
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * invoking the initializer method on the prototype of each class in the hierarchy.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _initHierarchy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @param {Object} userVals Object with configuration property name/value pairs
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren for (ci = classes.length-1; ci >= 0; ci--) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren if (constr._yuibuild && constr._yuibuild.exts && !constr._yuibuild.dynamic) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren for (ei = 0, el = constr._yuibuild.exts.length; ei < el; ei++) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren constr._yuibuild.exts[ei].apply(this, arguments);
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren this.addAttrs(this._filterAttrCfgs(constr, attrCfgs), userVals, lazy);
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren if (constrProto.hasOwnProperty(INITIALIZER)) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren constrProto.initializer.apply(this, arguments);
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Destroys the class hierarchy for this instance by invoking
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * the descructor method on the prototype of each class in the hierarchy.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method _destroyHierarchy
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren for (ci = 0, cl = classes.length; ci < cl; ci++) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren if (constrProto.hasOwnProperty(DESTRUCTOR)) {
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren constrProto.destructor.apply(this, arguments);
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Default toString implementation. Provides the constructor NAME
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * and the instance ID.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method toString
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @return {String} String representation for this object
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren return this.constructor.NAME + "[" + Y.stamp(this) + "]";
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren // Straightup augment, no wrapper functions
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Alias for <a href="Plugin.Host.html#method_Plugin.Host.plug">Plugin.Host.plug</a>. See aliased
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * method for argument and return value details.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method Base.plug
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * Alias for <a href="Plugin.Host.html#method_Plugin.Host.unplug">Plugin.Host.unplug</a>. See the
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * aliased method for argument and return value details.
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren * @method Base.unplug
8e7d713a6c785615b5688f96304ae151241dc885Eduardo Lundgren // Fix constructor