AttributeCore Class
AttributeCore provides the lightest level of configurable attribute support. It is designed to be augmented on to a host class, and provides the host with the ability to configure attributes to store and retrieve state, but without support for attribute change events.
For example, attributes added to the host can be configured:
- As read only.
- As write once.
- With a setter function, which can be used to manipulate values passed to Attribute's set method, before they are stored.
- With a getter function, which can be used to manipulate stored values, before they are returned by Attribute's get method.
- With a validator function, to validate values before they are stored.
See the addAttr method, for the complete set of configuration options available for attributes.
Object/Classes based on AttributeCore can augment AttributeObservable
(with true for overwrite) and AttributeExtras to add attribute event and
additional, less commonly used attribute methods, such as modifyAttr, removeAttr and reset.
Methods
_addAttrs
-
cfgs -
values -
lazy
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:
-
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.
_addLazyAttr
-
name -
[lazyCfg]
Finishes initializing an attribute which has been lazily added.
_addOutOfOrder
-
name -
cfg
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: ...
}
});_getAttr
-
name
Provides the common implementation for the public get method, allowing Attribute hosts to over-ride either method.
See get for argument details.
Parameters:
-
nameStringThe name of the attribute.
Returns:
The value of the attribute.
_getAttrInitVal
-
attr -
cfg -
initValues
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:
The initial value of the attribute.
_getAttrs
-
attrs
Implementation behind the public getAttrs method, to get multiple attribute values.
Parameters:
Returns:
An object with attribute name/value pairs.
_getStateVal
-
name -
[cfg]
Gets the stored value for the attribute, from either the internal state object, or the state proxy if it exits
Parameters:
Returns:
The stored value of the attribute
_initAttrHost
-
attrs -
values -
lazy
Constructor logic for attributes. Initializes the host state, and sets up the inital attributes passed to the constructor.
Parameters:
-
attrsObjectThe 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.
-
valuesObjectThe 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.
-
lazyBooleanWhether or not to add attributes lazily (passed through to addAttrs).
_initAttrs
-
attrs -
values -
lazy
Utility method to set up initial attributes defined during construction, either through the constructor.ATTRS property, or explicitly passed in.
Parameters:
-
attrsObjectThe 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.
-
valuesObjectThe 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.
-
lazyBooleanWhether or not to add attributes lazily (passed through to addAttrs).
_isLazyAttr
-
name
Checks whether or not the attribute is one which has been added lazily and still requires initialization.
Parameters:
-
nameStringThe name of the attribute
Returns:
true if it's a lazily added attribute, false otherwise.
_normAttrVals
-
valueHash
Utility method to normalize attribute values. The base implementation simply merges the hash to protect the original.
Parameters:
-
valueHashObjectAn object with attribute name/value pairs
Returns:
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
-
attrs
Utility method to protect an attribute configuration hash, by merging the entire object and the individual attr config objects.
Parameters:
-
attrsObjectA hash of attribute to configuration object pairs.
Returns:
A protected version of the attrs argument.
_set
-
name -
val -
[opts]
Allows setting of readOnly/writeOnce attributes. See set for argument details.
Parameters:
Returns:
A reference to the host object.
_setAttr
-
name -
value -
[opts] -
force
Provides the common implementation for the public set and protected _set methods.
See set for argument details.
Parameters:
Returns:
A reference to the host object.
_setAttrs
-
attrs -
[opts]
Implementation behind the public setAttrs method, to set multiple attribute values.
Parameters:
Returns:
A reference to the host object.
_setAttrVal
-
attrName -
subAttrName -
prevVal -
newVal -
[opts] -
[attrCfg]
Updates the stored value of the attribute in the privately held State object, if validation and setter passes.
Parameters:
-
attrNameStringThe attribute name.
-
subAttrNameStringThe sub-attribute name, if setting a sub-attribute property ("x.y.z").
-
prevValAnyThe currently stored value of the attribute.
-
newValAnyThe value which is going to be stored.
-
[opts]Object optionalOptional data providing the circumstances for the change.
-
[attrCfg]Object optionalOptional config hash for the attribute. This is added for performance along the critical path, where the calling method has already obtained the config from state.
Returns:
true if the new attribute value was stored, false if not.
_setStateVal
-
name -
value
Sets the stored value for the attribute, in either the internal state object, or the state proxy if it exits
Parameters:
-
nameStringThe name of the attribute
-
valueAnyThe value of the attribute
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.
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.
protectAttrs
-
attrs
Utility method to protect an attribute configuration hash, by merging the entire object and the individual attr config objects.
Parameters:
-
attrsObjectA hash of attribute to configuration object pairs.
Returns:
A protected version of the attrs argument.
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
_ATTR_CFG
Array
protected
static
The list of properties which can be configured for each attribute (e.g. setter, getter, writeOnce etc.).
This property is used internally as a whitelist for faster Y.mix operations.
INVALID_VALUE
Object
final
static
The value to return from an attribute setter in order to prevent the set from going through.
You can return this value from your setter if you wish to combine validator and setter functionality into a single setter function, which either returns the massaged value to be stored or AttributeCore.INVALID_VALUE to prevent invalid values from being stored.