BaseCore Class
The BaseCore class, is the lightest version of Base, and provides Base's basic lifecycle management and ATTRS construction support, but doesn't fire init/destroy or attribute change events.
BaseCore 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 BaseCore.
Classes which require attribute support, but don't intend to use/expose attribute change events can extend BaseCore instead of Base for optimal kweight and runtime performance.
3.11.0 BACK COMPAT NOTE FOR COMPONENT DEVELOPERS
Prior to version 3.11.0, ATTRS would get added a class at a time. That is:
for each (class in the hierarchy) {
Call the class Extension constructors.
Add the class ATTRS.
Call the class initializer
Call the class Extension initializers.
}
As of 3.11.0, ATTRS from all classes in the hierarchy are added in one addAttrs call
before any initializers are called. That is, the flow becomes:
for each (class in the hierarchy) {
Call the class Extension constructors.
}
Add ATTRS for all classes
for each (class in the hierarchy) {
Call the class initializer.
Call the class Extension initializers.
}
Adding all ATTRS at once 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. It also leaves us with a cleaner order of operation flow moving
forward.
However, it may require component developers to upgrade their components, for the following scenarios:
- It impacts components which may have
setter,getterorvalueFncode which expects a superclass' initializer to have run.
This is expected to be rare, but to support it, Base now 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 for example).
- Extension developers may need to move code from Extension constructors to
initializers
Older extensions, which were written before initializer support was added, had a lot of
initialization code in their constructors. For example, code which acccessed superclass
attributes. With the new flow this code would not be able to see attributes. The recommendation
is to move this initialization code to an initializer on the Extension, which was the
recommendation for anything created after initializer support for Extensions was added.
Constructor
BaseCore
-
cfg
Parameters:
-
cfgObjectObject with configuration property name/value pairs. The object can be used to provide initial values for the objects published attributes.
Item Index
Methods
Attributes
Methods
addAttr
-
name -
config -
lazy
Adds an attribute with the provided configuration to the host object.
The config argument object supports the following properties:
- value <Any>
- The initial value to set on the attribute
- valueFn <Function | String>
-
A function, which will return the initial value to set on the attribute. This is useful for cases where the attribute configuration is defined statically, but needs to reference the host instance ("this") to obtain an initial value. If both the value and valueFn properties are defined, the value returned by the valueFn has precedence over the value property, unless it returns undefined, in which case the value property is used.
valueFn can also be set to a string, representing the name of the instance method to be used to retrieve the value.
- readOnly <boolean>
- Whether or not the attribute is read only. Attributes having readOnly set to true cannot be modified by invoking the set method.
- writeOnce <boolean> or <string>
-
Whether or not the attribute is "write once". Attributes having writeOnce set to true,
can only have their values set once, be it through the default configuration,
constructor configuration arguments, or by invoking set.
The writeOnce attribute can also be set to the string "initOnly", in which case the attribute can only be set during initialization (when used with Base, this means it can only be set during construction)
- setter <Function | String>
-
The setter function used to massage or normalize the value passed to the set method for the attribute. The value returned by the setter will be the final stored value. Returning Attribute.INVALID_VALUE, from the setter will prevent the value from being stored.
setter can also be set to a string, representing the name of the instance method to be used as the setter function.
- getter <Function | String>
-
The getter function used to massage or normalize the value returned by the get method for the attribute. The value returned by the getter function is the value which will be returned to the user when they invoke get.
getter can also be set to a string, representing the name of the instance method to be used as the getter function.
- validator <Function | String>
-
The validator function invoked prior to setting the stored value. Returning false from the validator function will prevent the value from being stored.
validator can also be set to a string, representing the name of the instance method to be used as the validator function.
- lazyAdd <boolean>
- Whether or not to delay initialization of the attribute until the first call to get/set it. This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through the addAttrs method.
The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with the context ("this") set to the host object.
Configuration properties outside of the list mentioned above are considered private properties used internally by attribute, and are not intended for public use.
Parameters:
-
nameStringThe name of the attribute.
-
configObjectAn object with attribute configuration property/value pairs, specifying the configuration for the attribute.
NOTE: The configuration object is modified when adding an attribute, so if you need to protect the original values, you will need to merge the object.
-
lazyBoolean(optional) Whether or not to add this attribute lazily (on the first call to get/set).
Returns:
A reference to the host object.
addAttrs
-
cfgs -
values -
lazy
Configures a group of attributes, and sets initial values.
NOTE: This method does not isolate the configuration object by merging/cloning. The caller is responsible for merging/cloning the configuration object if required.
Parameters:
-
cfgsObjectAn object with attribute name/configuration pairs.
-
valuesObjectAn object with attribute name/value pairs, defining the initial values to apply. Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
-
lazyBooleanWhether or not to delay the intialization of these attributes until the first call to get/set. Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration. See addAttr.
Returns:
A reference to the host object.
attrAdded
-
name
Checks if the given attribute has been added to the host
Parameters:
-
nameStringThe name of the attribute to check.
Returns:
true if an attribute with the given name has been added, false if it hasn't. This method will return true for lazily added attributes.
destroy
()
BaseCore
chainable
Destroy lifecycle method. Invokes destructors for the class hierarchy.
Returns:
A reference to this object
get
-
name
Returns the current value of the attribute. If the attribute has been configured with a 'getter' function, this method will delegate to the 'getter' to obtain the value of the attribute.
Parameters:
-
nameStringThe name of the attribute. If the value of the attribute is an Object, dot notation can be used to obtain the value of a property of the object (e.g.
get("x.y.z"))
Returns:
The value of the attribute
getAttrs
-
attrs
Gets multiple attribute values.
Parameters:
Returns:
An object with attribute name/value pairs.
init
-
cfg
Init lifecycle method, invoked during construction. Sets up attributes and invokes initializers for the class hierarchy.
Parameters:
-
cfgObjectObject with configuration property name/value pairs
Returns:
A reference to this object
modifyAttrs
-
[ctor] -
configs
Provides a way to safely modify a Y.BaseCore subclass' static ATTRS
after the class has been defined or created.
BaseCore-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.
set
-
name -
value -
[opts]
Sets the value of an attribute.
Parameters:
-
nameStringThe name of the attribute. If the current value of the attribute is an Object, dot notation can be used to set the value of a property within the object (e.g.
set("x.y.z", 5)). -
valueAnyThe value to set the attribute to.
-
[opts]Object optionalOptional data providing the circumstances for the change.
Returns:
A reference to the host object.
Properties
ATTRS
Object
static
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 AttributeCore'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.
NAME
String
static
The string to be used to identify instances of this class.
Classes extending BaseCore, should define their own static NAME property, which should be camelCase by convention (e.g. MyClass.NAME = "myClass";).
Attributes
destroyed
Boolean
readonly
Flag indicating whether or not this object has been through the destroy lifecycle phase.
Default: false
Fires event destroyedChange
Fires when the value for the configuration attribute destroyed is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
initialized
Boolean
readonly
Flag indicating whether or not this object has been through the init lifecycle phase.
Default: false
Fires event initializedChange
Fires when the value for the configuration attribute initialized is
changed. You can listen for the event using the on method if you
wish to be notified before the attribute's value has changed, or
using the after method if you wish to be notified after the
attribute's value has changed.
Parameters:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added: