Class Attribute
- uses
EventTarget
Attribute provides configurable attribute support along with attribute change events. 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,
along with 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
.
NOTE: Most implementations will be better off extending the Base class,
instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration
of attributes for derived classes, accounting for values passed into the constructor.
Properties
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.
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
Attribute.INVALID_VALUE to prevent invalid values from being stored.
Methods
protected
Any
_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:
-
name
<String>
The name of the attribute.
- Returns:
Any
- The value of the attribute.
Chainable: This method is chainable.
protected
Object
_getAttrs
(
attrs
)
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.
protected
Object
_protectAttrs
(
attrs
)
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.
protected
Object
_set
(
name
,
val
,
opts
)
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.
Chainable: This method is chainable.
protected
Object
_setAttr
(
name
,
value
,
opts
,
force
)
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.
Chainable: This method is chainable.
protected
Object
_setAttrs
(
attrs
)
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.
Chainable: This method is chainable.
Object
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 defined, valueFn has precedence over the value property.
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>
- 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.
- 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.
Chainable: This method is chainable.
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:
-
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.
Chainable: This method is chainable.
boolean
attrAdded
(
name
)
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.
Any
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:
-
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
Object
getAttrs
(
attrs
)
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.
void
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.
void
removeAttr
(
name
)
Removes an attribute from the host object
- Parameters:
-
name
<String>
The name of the attribute to be removed.
Object
reset
(
name
)
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.
Chainable: This method is chainable.
Object
set
(
name
,
value
,
opts
)
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.
Chainable: This method is chainable.
Object
setAttrs
(
attrs
)
Sets multiple attribute values.
- Parameters:
-
attrs
<Object>
An object with attributes name/value pairs.
- Returns:
Object
- A reference to the host object.
Chainable: This method is chainable.