+ * 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. + *
+ * + *+ * **NOTE:** Prior to version 3.11.0, ATTRS would get added a class at a time. That is, + * Base would loop through each class in the hierarchy, and add the class' ATTRS, and + * then call it's initializer, and move on to the subclass' ATTRS and initializer. As of + * 3.11.0, ATTRS from all classes in the hierarchy are added in one `addAttrs` call before + * any initializers are called. This fixes subtle edge-case issues with subclass ATTRS overriding + * superclass `setter`, `getter` or `valueFn` definitions and being unable to get/set attributes + * defined by the subclass. This order of operation change may impact `setter`, `getter` or `valueFn` + * code which expects a superclass' initializer to have run. This is expected to be rare, but to support + * it, Base supports a `_preAddAttrs()`, method hook (same signature as `addAttrs`). Components can + * implement this method on their prototype for edge cases which do require finer control over + * the order in which attributes are added (see widget-htmlparser). + *
+ * + *+ * 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 BaseCore + * @uses BaseObservable + * @uses AttributeCore + * @uses AttributeObservable + * @uses AttributeExtras + * @uses EventTarget + * + * @param {Object} config Object with configuration property name/value pairs. The object can be + * used to provide default values for the objects published attributes. + * + *+ * The config object can also contain the following non-attribute properties, providing a convenient + * way to configure events listeners and plugins for the instance, as part of the constructor call: + *
+ * + *+ * 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 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 ATTRS + * @type Object + * @static + */ + Base.ATTRS = AttributeCore.protectAttrs(BaseCore.ATTRS); + + /** + Provides a way to safely modify a `Y.Base` subclass' static `ATTRS` after + the class has been defined or created. + + Base-based classes cache information about the class hierarchy in order to + efficiently create instances. This cache includes includes the aggregated + `ATTRS` configs. If the static `ATTRS` configs need to be modified after the + class has been defined or create, then use this method which will make sure + to clear any cached data before making any modifications. + + @method modifyAttrs + @param {Function} [ctor] The constructor function whose `ATTRS` should be + modified. If a `ctor` function is not specified, then `this` is assumed + to be the constructor which hosts the `ATTRS`. + @param {Object} configs The collection of `ATTRS` configs to mix with the + existing attribute configurations. + @static + @since 3.10.0 + **/ + Base.modifyAttrs = BaseCore.modifyAttrs; + + Y.mix(Base, BaseCore, false, null, 1); + Y.mix(Base, AttributeExtras, false, null, 1); + + // Needs to be `true`, to overwrite methods from `BaseCore`. + Y.mix(Base, BaseObservable, true, null, 1); + + // Fix constructor + Base.prototype.constructor = Base; + + Y.Base = Base; + + +}, '@VERSION@', {"requires": ["attribute-base", "base-core", "base-observable"]});