BaseCore Class - YUI Library (original) (raw)

Methods

_addAttrs

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:

_addLazyAttr

private

Finishes initializing an attribute which has been lazily added.

Parameters:

_addOutOfOrder

private

Utility method used by get/set to add attributes encountered out of order when calling addAttrs().

For example, if:

this.addAttrs({
     foo: {
         setter: function() {
            // make sure this bar is available when foo is added
            this.get("bar");
         }
     },
     bar: {
         value: ...
     }
});

Parameters:

_aggregateAttrs

Object private

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:

Returns:

Object:

The aggregate set of ATTRS definitions for the instance

_attrCfgHash

() private

Utility method to define the attribute hash used to filter/whitelist property mixes for this class for iteration performance reasons.

_baseDestroy

() private

Internal destroy implementation for BaseCore

_baseInit

() private

Internal initialization implementation for BaseCore

_cloneDefaultValue

private

This method assumes that the value has already been checked to be an object. Since it's on a critical path, we don't want to re-do the check.

_destroyHierarchy

() private

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

_filterAdHocAttrs

Object private

Parameters:

Returns:

Object:

The set of adhoc attributes passed in, in the form of an object with attribute name/configuration pairs.

_getAttr

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:

Returns:

Any:

The value of the attribute.

_getAttrCfgs

() Object protected

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

Any private

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:

Returns:

Any:

The initial value of the attribute.

_getAttrs

Object protected

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

Parameters:

Returns:

Object:

An object with attribute name/value pairs.

_getClasses

() Function[] protected

Returns the class hierarchy for this object, with BaseCore 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.

_getInstanceAttrCfgs

Object private

A helper method used to isolate the attrs config for this instance to pass to addAttrs, from the static cached ATTRS for the class.

Parameters:

Returns:

Object:

The set of attributes to be added for this instance, suitable for passing through to addAttrs.

_getStateVal

Any private

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

Parameters:

Returns:

Any:

The stored value of the attribute

_initAttrHost

private

Constructor logic for attributes. Initializes the host state, and sets up the inital attributes passed to the constructor.

Parameters:

_initAttribute

() private

Initializes AttributeCore

_initAttrs

protected

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

Parameters:

_initBase

private

Internal construction logic for BaseCore.

Parameters:

_initHierarchy

private

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:

_initHierarchyData

() private

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.

_isLazyAttr

Boolean private

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

Parameters:

Returns:

Boolean:

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

_normAttrVals

Object private

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

Parameters:

Returns:

Object:

An object literal with 2 properties - "simple" and "complex", containing simple and complex attribute values respectively keyed by the top level attribute name, or null, if valueHash is falsey.

_protectAttrs

Object deprecated protected

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

Parameters:

Returns:

Object:

A protected version of the attrs argument.

_set

Object protected chainable

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

Parameters:

Returns:

Object:

A reference to the host object.

_setAttr

(

)

Object protected chainable

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

See set for argument details.

Parameters:

Returns:

Object:

A reference to the host object.

_setAttrs

Object protected chainable

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

Parameters:

Returns:

Object:

A reference to the host object.

_setAttrVal

(

)

Boolean private

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

Parameters:

Returns:

Boolean:

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

_setStateVal

private

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

Parameters:

addAttr

Object chainable

Adds an attribute with the provided configuration to the host object.

The config argument object supports the following properties:

value

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

Whether or not the attribute is read only. Attributes having readOnly set to true cannot be modified by invoking the set method.

writeOnce or

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. ReturningAttribute.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

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:

Returns:

Object:

A reference to the host object.

addAttrs

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:

Returns:

Object:

A reference to the host object.

attrAdded

Boolean

Checks if the given attribute has been added to the host

Parameters:

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.

destroy

() BaseCore chainable

Destroy lifecycle method. Invokes destructors for the class hierarchy.

Returns:

get

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:

Returns:

Any:

The value of the attribute

getAttrs

Object

Gets multiple attribute values.

Parameters:

Returns:

Object:

An object with attribute name/value pairs.

init

BaseCore chainable

Init lifecycle method, invoked during construction. Sets up attributes and invokes initializers for the class hierarchy.

Parameters:

Returns:

modifyAttrs

static

Provides a way to safely modify a Y.BaseCore subclass' static ATTRSafter 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 aggregatedATTRS 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.

Parameters:

set

Object chainable

Sets the value of an attribute.

Parameters:

Returns:

Object:

A reference to the host object.

setAttrs

Object chainable

Sets multiple attribute values.

Parameters:

Returns:

Object:

A reference to the host object.

toString

() String

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

Returns:

String:

String representation for this object

Properties

_allowAdHocAttrs

Boolean protected

This property controls whether or not instances of this class should allow users to add ad-hoc attributes through the constructor configuration hash.

AdHoc attributes are attributes which are not defined by the class, and are not handled by the MyClass._NON_ATTRS_CFG

Default: undefined (false)

_ATTR_CFG

Array private static

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

_NON_ATTRS_CFG

Array private static

The array of non-attribute configuration properties supported by this class.

For example BaseCore defines a "plugins" configuration property which should not be set up as an attribute. This property is primarily required so that when _allowAdHocAttrs is enabled by a class, non-attribute configuration properties don't get added as ad-hoc attributes.

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

name

String deprecated

The string used to identify the class of this object.

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:

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: