Version 3.4.1
Show:

Base Class

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.

Constructor

Base

(
  • config
)

Defined in base/js/Base.js:43

Parameters:

  • config Object
    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:
    on
    An event name to listener function map, to register event listeners for the "on" moment of the event. A constructor convenience property for the on method.
    after
    An event name to listener function map, to register event listeners for the "after" moment of the event. A constructor convenience property for the after method.
    bubbleTargets
    An object, or array of objects, to register as bubble targets for bubbled events fired by this instance. A constructor convenience property for the addTarget method.
    plugins
    A plugin, or array of plugins to be plugged into the instance (see PluginHost's plug method for signature details). A constructor convenience property for the plug method.

Methods

_addAttrs

(
  • cfgs
  • values
  • lazy
)
private

Implementation behind the public addAttrs method.

This method is invoked directly by get if it encounters a scenario in which an attribute's valueFn attempts to obtain the value an attribute in the same group of attributes, which has not yet been added (on demand initialization).

Parameters:

  • cfgs Object
    An object with attribute name/configuration pairs.
  • values Object
    An 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.
  • lazy Boolean
    Whether 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.

_addLazyAttr

(
  • name
)
private

Finishes initializing an attribute which has been lazily added.

Parameters:

  • name Object
    The name of the attribute

_aggregateAttrs

(
  • allAttrs
)
Object private

Defined in base/js/Base.js:436

A helper method, used by _initHierarchyData to aggregate attribute configuration across the instances class hierarchy.

The method will protect 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).

Parameters:

  • allAttrs Array
    An array of ATTRS definitions across classes in the hierarchy (subclass first, Base last)

Returns:

Object: The aggregate set of ATTRS definitions for the instance

_defAttrChangeFn

(
  • e
)
private

Default function for attribute change events.

Parameters:

  • e EventFacade
    The event object for attribute change events.

_defDestroyFn

(
  • e
)
protected

Defined in base/js/Base.js:329

Default destroy event handler

Parameters:

_defInitFn

(
  • e
)
protected

Defined in base/js/Base.js:312

Default init event handler

Parameters:

  • e EventFacade
    Event object, with a cfg property which refers to the configuration object passed to the constructor.

_destroyHierarchy

() private

Defined in base/js/Base.js:564

Destroys the class hierarchy for this instance by invoking the destructor method on the prototype of each class in the hierarchy.

_destroyPlugins

() private

Unplugs and destroys all plugins on the host

_filterAttrCfs

(
  • clazz
  • allCfgs
)
Object private

Defined in base/js/Base.js:376

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 .

Parameters:

  • clazz Function
    The class for which the desired attributes are required.
  • allCfgs Object
    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.

Returns:

Object: The set of attributes belonging to the class passed in, in the form of an object with attribute name/configuration pairs.

_fireAttrChange

(
  • attrName
  • subAttrName
  • currVal
  • newVal
  • opts
)
private

Utility method to help setup the event payload and fire the attribute change event.

Parameters:

  • attrName String
    The name of the attribute
  • subAttrName String
    The full path of the property being changed, if this is a sub-attribute value being change. Otherwise null.
  • currVal Any
    The current value of the attribute
  • newVal Any
    The new value of the attribute
  • opts Object
    Any additional event data to mix into the attribute change event's event facade.

_getAttr

(
  • name
)
Any protected chainable

Provides the common implementation for the public get method, allowing Attribute hosts to over-ride either method.

See get for argument details.

Parameters:

  • name String
    The name of the attribute.

Returns:

Any: The value of the attribute.

_getAttrCfg

(
  • name
)
Object protected

Returns an object with the configuration properties (and value) for the given attrubute. If attrName is not provided, returns the configuration properties for all attributes.

Parameters:

  • name String
    Optional. The attribute name. If not provided, the method will return the configuration for all attributes.

Returns:

Object: The configuration properties for the given attribute, or all attributes.

_getAttrCfgs

() Object protected

Defined in base/js/Base.js:360

Returns an aggregated set of attribute configurations, by traversing the class hierarchy.

Returns:

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.

_getAttrInitVal

(
  • attr
  • cfg
  • initValues
)
Any private

Inherited from Attribute but overwritten in attribute/js/Attribute.js:972

Returns the initial value of the given attribute from either the default configuration provided, or the over-ridden value if it exists in the set of initValues provided and the attribute is not read-only.

Parameters:

  • attr String
    The name of the attribute
  • cfg Object
    The attribute configuration object
  • initValues Object
    The object with simple and complex attribute name/value pairs returned from _normAttrVals

Returns:

Any: The initial value of the attribute.

_getAttrs

(
  • attrs
)
Object protected

Implementation behind the public getAttrs method, to get multiple attribute values.

Parameters:

  • attrs Array | boolean
    Optional. An array of attribute names. If omitted, all attribute values are returned. If set to true, all attributes modified from their initial values are returned.

Returns:

Object: An object with attribute name/value pairs.

_getClasses

() Function[] protected

Defined in base/js/Base.js:344

Returns the class hierarchy for this object, with Base being the last class in the array.

Returns:

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.

_getStateVal

(
  • name
)
Any private

Gets the stored value for the attribute, from either the internal state object, or the state proxy if it exits

Parameters:

  • name String
    The name of the attribute

Returns:

Any: The stored value of the attribute

_initAttrs

(
  • attrs
  • values
  • lazy
)
protected

Utility method to set up initial attributes defined during construction, either through the constructor.ATTRS property, or explicitly passed in.

Parameters:

  • attrs Object
    The attributes to add during construction (passed through to addAttrs). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
  • values Object
    The initial attribute values to apply (passed through to addAttrs). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
  • lazy Boolean
    Whether or not to add attributes lazily (passed through to addAttrs).

_initConfigPlugins

(
  • config
)
protected

A protected initialization method, used by the host class to initialize plugin configurations passed the constructor, through the config object.

Host objects should invoke this method at the appropriate time in their construction lifecycle.

Parameters:

  • config Object
    The configuration object passed to the constructor

_initHierarchy

(
  • userVals
)
private

Defined in base/js/Base.js:511

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.

Parameters:

  • userVals Object
    Object with configuration property name/value pairs

_initHierarchyData

() private

Defined in base/js/Base.js:408

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.

_initPlugins

(
  • config
)
private

Initializes static plugins registered on the host (using the Base.plug static method) and any plugins passed to the instance through the "plugins" configuration property.

Parameters:

  • config Config
    The configuration object with property name/value pairs.

_isLazyAttr

(
  • name
)
Boolean private

Checks whether or not the attribute is one which has been added lazily and still requires initialization.

Parameters:

  • name String
    The name of the attribute

Returns:

Boolean: true if it's a lazily added attribute, false otherwise.

_normAttrVals

(
  • valueHash
)
Object private

Inherited from Attribute but overwritten in attribute/js/Attribute.js:957

Utility method to normalize attribute values. The base implementation simply merges the hash to protect the original.

Parameters:

  • valueHash Object
    An object with attribute name/value pairs

Returns:

_preInitEventCfg

(
  • config
)
private

Defined in base/js/Base.js:232

Handles the special on, after and target properties which allow the user to easily configure on and after listeners as well as bubble targets during construction, prior to init.

Parameters:

  • config Object
    The user configuration object

_protectAttrs

(
  • attrs
)
Object protected

Utility method to protect an attribute configuration hash, by merging the entire object and the individual attr config objects.

Parameters:

  • attrs Object
    A hash of attribute to configuration object pairs.

Returns:

Object: A protected version of the attrs argument.

_set

(
  • name
  • val
  • opts
)
Object protected chainable

Allows setting of readOnly/writeOnce attributes. See set for argument details.

Parameters:

  • name String
    The name of the attribute.
  • val Any
    The value to set the attribute to.
  • opts Object
    (Optional) Optional event data to be mixed into the event facade passed to subscribers of the attribute's change event.

Returns:

Object: A reference to the host object.

_setAttr

(
  • name
  • value
  • opts
  • force
)
Object protected chainable

Provides the common implementation for the public set and protected _set methods.

See set for argument details.

Parameters:

  • name String
    The name of the attribute.
  • value Any
    The value to set the attribute to.
  • opts Object
    (Optional) Optional event data to be mixed into the event facade passed to subscribers of the attribute's change event.
  • force Boolean
    If true, allows the caller to set values for readOnly or writeOnce attributes which have already been set.

Returns:

Object: A reference to the host object.

_setAttrs

(
  • attrs
)
Object protected chainable

Implementation behind the public setAttrs method, to set multiple attribute values.

Parameters:

  • attrs Object
    An object with attributes name/value pairs.

Returns:

Object: A reference to the host object.

_setAttrVal

(
  • attrName
  • subAttrName
  • prevVal
  • newVal
)
Booolean private

Updates the stored value of the attribute in the privately held State object, if validation and setter passes.

Parameters:

  • attrName String
    The attribute name.
  • subAttrName String
    The sub-attribute name, if setting a sub-attribute property ("x.y.z").
  • prevVal Any
    The currently stored value of the attribute.
  • newVal Any
    The value which is going to be stored.

Returns:

Booolean: true if the new attribute value was stored, false if not.

_setStateVal

(
  • name
  • value
)
private

Sets the stored value for the attribute, in either the internal state object, or the state proxy if it exits

Parameters:

  • name String
    The name of the attribute
  • value Any
    The value of the attribute

addAttr

(
  • name
  • config
  • lazy
)
Object chainable

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.
broadcast <int>
If and how attribute change events for this attribute should be broadcast. See CustomEvent's broadcast property for valid values. By default attribute change events are not broadcast.
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:

  • name String
    The name of the attribute.
  • config Object
    An 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.
  • lazy Boolean
    (optional) Whether or not to add this attribute lazily (on the first call to get/set).

Returns:

Object: A reference to the host object.

addAttrs

(
  • cfgs
  • values
  • lazy
)
Object chainable

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:

  • cfgs Object
    An object with attribute name/configuration pairs.
  • values Object
    An 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.
  • lazy Boolean
    Whether 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:

Object: A reference to the host object.

attrAdded

(
  • name
)
Boolean

Checks if the given attribute has been added to the host

Parameters:

  • name String
    The name of the attribute to check.

Returns:

Boolean: 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.

build

(
  • name
  • main
  • extensions
  • cfg
)
Function deprecated static

Provided by the base-build module.

Defined in base/js/BaseBuild.js:208

Deprecated: Use the more convenient Base.create and Base.mix methods instead

Builds a custom constructor function (class) from the main function, and array of extension functions (classes) provided. The NAME field for the constructor function is defined by the first argument passed in.

The cfg object supports the following properties

dynamic <boolean>
If true (default), a completely new class is created which extends the main class, and acts as the host on which the extension classes are augmented. If false, the extensions classes are augmented directly to the main class, modifying the main class' prototype.
aggregates <String[]>
An array of static property names, which will get aggregated on to the built class, in addition to the default properties build will always aggregate as defined by the main class' static _buildCfg property.

Parameters:

  • name Function
    The name of the new class. Used to defined the NAME property for the new class.
  • main Function
    The main class on which to base the built class
  • extensions Function[]
    The set of extension classes which will be augmented/aggregated to the built class.
  • cfg Object
    Optional. Build configuration for the class (see description).

Returns:

Function: A custom class, created from the provided main and extension classes

create

(
  • name
  • main
  • extensions
  • px
  • sx
)
Function static

Provided by the base-build module.

Defined in base/js/BaseBuild.js:249

Creates a new class (constructor function) which extends the base class passed in as the second argument, and mixes in the array of extensions provided. Prototype properties or methods can be added to the new class, using the px argument (similar to Y.extend). Static properties or methods can be added to the new class, using the sx argument (similar to Y.extend).

Parameters:

  • name Function
    The name of the newly created class. Used to defined the NAME property for the new class.
  • main Function
    The base class which the new class should extend. This class needs to be Base or a class derived from base (e.g. Widget).
  • extensions Function[]
    The list of extensions which will be mixed into the built class.
  • px Object
    The set of prototype properties/methods to add to the built class.
  • sx Object
    The set of static properties/methods to add to the built class.

Returns:

Function: The newly created class.

destroy

() Base chainable

Defined in base/js/Base.js:266

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.

Returns:

Base: A reference to this object

get

(
  • name
)
Any

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:

  • name String
    The 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:

Any: The value of the attribute

getAttrs

(
  • attrs
)
Object

Gets multiple attribute values.

Parameters:

  • attrs Array | boolean
    Optional. An array of attribute names. If omitted, all attribute values are returned. If set to true, all attributes modified from their initial values are returned.

Returns:

Object: An object with attribute name/value pairs.

hasPlugin

(
  • ns
)
Boolean

Determines if a plugin has plugged into this host.

Parameters:

  • ns String
    The plugin's namespace

Returns:

Boolean: returns true, if the plugin has been plugged into this host, false otherwise.

init

(
  • config
)
Base chainable

Defined in base/js/Base.js:186

Init lifecycle method, invoked during construction. Fires the init event prior to setting up attributes and invoking initializers for the class hierarchy.

Parameters:

  • config Object
    Object with configuration property name/value pairs

Returns:

Base: A reference to this object

mix

(
  • main
  • extensions
)
Function static

Provided by the base-build module.

Defined in base/js/BaseBuild.js:270

Mixes in a list of extensions to an existing class.

Parameters:

  • main Function
    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)
  • extensions Function[]
    The set of extension classes which will mixed into the existing main class.

Returns:

Function: The modified main class, with extensions mixed in.

modifyAttr

(
  • name
  • config
)

Updates the configuration of an attribute which has already been added.

The properties which can be modified through this interface are limited to the following subset of attributes, which can be safely modified after a value has already been set on the attribute: readOnly, writeOnce, broadcast and getter.

Parameters:

  • name String
    The name of the attribute whose configuration is to be updated.
  • config Object
    An object with configuration property/value pairs, specifying the configuration properties to modify.

plug

() static

Inherited from Plugin.Host but overwritten in base/js/BasePluginHost.js:15

Alias for Plugin.Host.plug. See aliased method for argument and return value details.

removeAttr

(
  • name
)

Removes an attribute from the host object

Parameters:

  • name String
    The name of the attribute to be removed.

reset

(
  • name
)
Object chainable

Resets the attribute (or all attributes) to its initial value, as long as the attribute is not readOnly, or writeOnce.

Parameters:

  • name String
    Optional. The name of the attribute to reset. If omitted, all attributes are reset.

Returns:

Object: A reference to the host object.

set

(
  • name
  • value
  • opts
)
Object chainable

Sets the value of an attribute.

Parameters:

  • name String
    The 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)).
  • value Any
    The value to set the attribute to.
  • opts Object
    (Optional) Optional event data to be mixed into the event facade passed to subscribers of the attribute's change event. This can be used as a flexible way to identify the source of a call to set, allowing the developer to distinguish between set called internally by the host, vs. set called externally by the application developer.

Returns:

Object: A reference to the host object.

setAttrs

(
  • attrs
)
Object chainable

Sets multiple attribute values.

Parameters:

  • attrs Object
    An object with attributes name/value pairs.

Returns:

Object: A reference to the host object.

toString

() String

Defined in base/js/Base.js:597

Default toString implementation. Provides the constructor NAME and the instance guid, if set.

Returns:

String: String representation for this object

unplug

() static

Inherited from Plugin.Host but overwritten in base/js/BasePluginHost.js:24

Alias for Plugin.Host.unplug. See the aliased method for argument and return value details.

Properties

_ATTR_CFG

Array private static

Defined in base/js/Base.js:112

The list of properties which can be configured for each attribute (e.g. setter, getter, writeOnce, readOnly etc.)

_buildCfg

Object private final static

Provided by the base-build module.

Defined in base/js/BaseBuild.js:282

The build configuration for the Base class.

Defines the static fields which need to be aggregated when the Base class is used as the main class passed to the Base.build method.

ATTRS

Object static

Defined in base/js/Base.js:140

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.

name

String deprecated

Defined in base/js/Base.js:99

Deprecated: Use this.constructor.NAME

The string used to identify the class of this object.

NAME

String static

Defined in base/js/Base.js:124

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";).

Attributes

destroyed

boolean

Defined in base/js/Base.js:169

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:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

initialized

boolean

Defined in base/js/Base.js:155

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:

  • e EventFacade
    An Event Facade object with the following attribute-specific properties added:
    • prevVal Any
      The value of the attribute, prior to it being set.
    • newVal Any
      The value the attribute is to be set to.
    • attrName String
      The name of the attribute being set.
    • subAttrName String
      If setting a property within the attribute's value, the name of the sub-attribute property being set.

Events

destroy

Defined in base/js/Base.js:284

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 Payload:

init

Defined in base/js/Base.js:201

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 Payload:

  • e EventFacade
    Event object, with a cfg property which refers to the configuration object passed to the constructor.

This project is kindly supported by Creative Agency, Imaginaire Digital in Nottingham, UK.