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.
Item Index
Properties
- INVALID_VALUE static
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.
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
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.