Attribute.js revision 3681658caa31e1b61b575d03cde5d5798b101eaa
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Managed Attribute Provider
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @module attribute
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith var O = Y.Object,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith DOT = ".",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith CHANGE = "Change",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith GETTER = "getter",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith SETTER = "setter",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith VALUE = "value",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith ADDED = "added",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith INITIALIZING = "initializing",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith INIT_VALUE = "initValue",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith READ_ONLY = "readOnly",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith WRITE_ONCE = "writeOnce",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith VALIDATOR = "validator",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith PUBLISHED = "published",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith BROADCAST = "broadcast",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith INVALID_VALUE,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith EventTarget = Y.EventTarget;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Attribute provides managed attribute support.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * </p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * The class is designed to be augmented onto a host class,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * and allows the host to support getter/setter methods for attributes,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * initial configuration support and attribute change events.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * </p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <p>Attributes added to the host can:</p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <ul>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <li>Be defined as read-only.</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <li>Be defined as write-once.</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <li>Be defined with a setter function, used to manipulate
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * values passed to Attribute's set method, before they are stored.</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <li>Be defined with a validator function, to validate values before they are stored.</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <li>Be defined with a getter function, which can be used to manipulate stored values,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * before they are returned by Attribute's get method.</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * </ul>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <p>See the <a href="#method_addAtt">addAttr</a> method, for details about how to add attributes with
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * a specific configuration</p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @class Attribute
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @uses Event.Target
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith function Attribute() {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Y.log('Attribute constructor called', 'info', 'attribute');
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Perf tweak - avoid creating event literals if not required.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith this._ATTR_E_FACADE = {};
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith EventTarget.call(this, {emitFacade:true});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith this._conf = new Y.State();
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Attribute.INVALID_VALUE = {};
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith INVALID_VALUE = Attribute.INVALID_VALUE;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Attribute.prototype = {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Adds an attribute with the provided configuration to the host object. Intended
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * to be used by the host object to setup it's set of available attributes.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * </p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * The config argument object literal supports the following optional properties:
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * </p>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dl>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dt>value &#60;Any&#62;</dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dd>The initial value to set on the attribute</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dt>readOnly &#60;Boolean&#62;</dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dd>Whether or not the attribute is read only. Attributes having readOnly set to true
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * cannot be set by invoking the set method.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dt>writeOnce &#60;Boolean&#62;</dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dd>Whether or not the attribute is "write once". Attributes having writeOnce set to true,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * can only have their values set once, be it through the default configuration,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * constructor configuration arguments, or by invoking set.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dt>setter &#60;Function&#62;</dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dd>The setter function to be invoked (within the context of the host object) before
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * the attribute is stored by a call to the setter method. The value returned by the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * setter function will be the finally stored value.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dt>getter &#60;Function&#62;</dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dd>The getter function to be invoked (within the context of the host object) before
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * the stored values is returned to a user invoking the getter method for the attribute.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * The value returned by the getter function is the final value which will be returned to the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * user when they invoke get.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dt>validator &#60;Function&#62;</dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <dd>The validator function which is invoked prior to setting the stored value. Returning
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * false from the validator function will prevent the value from being stored</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * </dl>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @method addAttr
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {String} name The attribute key
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {Object} config (optional) An object literal specifying the configuration for the attribute.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * <strong>NOTE:</strong> The config object is modified when adding an attribute,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * so if you need to protect the original values, you will need to merge or clone the object.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @chainable
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith addAttr: function(name, config) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Y.log('Adding attribute: ' + name, 'info', 'attribute');
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith if (!this.attrAdded(name)) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith config = config || {};
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith var value,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith hasValue = (VALUE in config),
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith conf = this._conf;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith if (config[READ_ONLY] && !hasValue) { Y.log('readOnly attribute: ' + name + ', added without an initial value. Value will be set on intial call to set', 'warn', 'attribute');}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith if(hasValue) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // We'll go through set, don't want to set value in _conf directory
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith value = config.value;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith delete config.value;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith config[ADDED] = true;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith config[INITIALIZING] = true;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith conf.addAll(name, config);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith if (hasValue) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Go through set, so that raw values get normalized/validated
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith this.set(name, value);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith conf.remove(name, INITIALIZING);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith } else {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Y.log('Attribute: ' + name + ' already exists. Cannot add it again without removing it first', 'warn', 'attribute');
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return this;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Tests if the given attribute has been added to the host
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @method attrAdded
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {String} name The name of the attribute to check.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @return boolean, true if an attribute with the given name has been added.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith attrAdded: function(name) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return !!(this._conf.get(name, ADDED));
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Removes an attribute.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @method removeAttr
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {String} name The attribute key
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith removeAttr: function(name) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith this._conf.removeAll(name);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Returns the current value of the attribute. If the attribute
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * has been configured with a 'getter' function, this method will delegate
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * to the 'getter' to obtain the value of the attribute.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * The 'getter' will be passed the current value of the attribute
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * as the only argument.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @method get
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {String} name The attribute whose value will be returned. If
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * the value of the attribute is an Object, dot notation can be used to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * obtain the value of a property of the object (e.g. <code>get("x.y.z")</code>)
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @return {Any} The current value of the attribute
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith get : function(name) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith var fullName = name,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith conf = this._conf,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith path,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith getter,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith val;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith if (name.indexOf(DOT) !== -1) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith path = name.split(DOT);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith name = path.shift();
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith val = conf.get(name, VALUE);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith getter = conf.get(name, GETTER);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith val = (getter) ? getter.call(this, val, fullName) : val;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith val = (path) ? O.getValue(val, path) : val;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return val;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Sets the value of an attribute.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @method set
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @chainable
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {String} name The name of the attribute. Note, if the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * value of the attribute is an Object, dot notation can be used
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * to set the value of a property within the object (e.g. <code>set("x.y.z", 5)</code>).
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {Any} value The value to apply to the attribute
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {Object} opts Optional event data. This object will be mixed into
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * the event facade passed as the first argument to subscribers
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * of attribute change events
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * @return {Object} Reference to the host object
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith */
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith set : function(name, val, opts) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith return this._setAttr(name, val, opts);
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith },
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith /**
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * Resets the given attribute or all attributes to the initial value, if the attribute
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * is not readOnly, or writeOnce.
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith *
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * @method reset
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * @param {String} name optional An attribute to reset. If omitted, all attributes are reset.
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * @chainable
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith */
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith reset : function(name) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith if (name) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith this.set(name, this._conf.get(name, INIT_VALUE));
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith } else {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith var initVals = this._conf.data.initValue;
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith Y.each(initVals, function(v, n) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith this.set(n, v);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }, this);
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith }
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith return this;
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith /**
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * Allows setting of readOnly/writeOnce attributes.
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith *
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * @method _set
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith * @protected
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @chainable
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @return {Object} Reference to the host object
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith _set : function(name, val, opts) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return this._setAttr(name, val, opts, true);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith /**
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * Internal set implementation
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @method _setAttr
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @protected
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @chainable
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @param {String} name The name of the attribute. Note, if the
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * value of the attribute is an Object, dot notation can be used
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * to set the value of a property within the object
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * (e.g. <code>set("x.y.z", 5)</code>).
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith *
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * @param {Any} value The value to apply to the attribute
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith *
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * @param {Object} opts Optional event data. This object will be mixed into
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * the event facade passed as the first argument to subscribers
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * of attribute change events
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith *
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * @param {boolean} force If true, allows the caller to set values for
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith * readOnly or writeOnce attributes which have already been set.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith *
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith * @return {Object} Reference to the host object
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith */
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith _setAttr : function(name, val, opts, force) {
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith var allowSet = true,
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith conf = this._conf,
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith data = conf.data,
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith initialSet,
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith strPath,
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith path,
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith currVal;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith if (name.indexOf(DOT) !== -1) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith strPath = name;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith path = name.split(DOT);
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith name = path.shift();
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith }
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith initialSet = (!data.value || !(name in data.value));
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith if (!this.attrAdded(name)) {
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Y.log('Set attribute:' + name + ', aborted; Attribute is not configured', 'warn', 'attribute');
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith } else {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith if (!initialSet && !force) {
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith if (conf.get(name, WRITE_ONCE)) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Y.log('Set attribute:' + name + ', aborted; Attribute is writeOnce', 'warn', 'attribute');
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith allowSet = false;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }
if (conf.get(name, READ_ONLY)) {
Y.log('Set attribute:' + name + ', aborted; Attribute is readOnly', 'warn', 'attribute');
allowSet = false;
}
}
if (allowSet) {
currVal = this.get(name);
if (path) {
val = O.setValue(Y.clone(currVal), path, val);
if (val === undefined) {
Y.log('Set attribute path:' + strPath + ', aborted; Path is invalid', 'warn', 'attribute');
allowSet = false;
}
}
if (allowSet) {
if (conf.get(name, INITIALIZING)) {
this._setAttrVal(name, strPath, currVal, val);
} else {
this._fireAttrChange(name, strPath, currVal, val, opts);
}
}
}
}
return this;
},
/**
* Utility method to help setup the event payload and
* fire the attribute change event.
*
* @method _fireAttrChange
* @private
* @param {String} attrName The name of the attribute
* @param {String} subAttrName The full path of the property being changed,
* if this is a sub-attribute value being change. Otherwise null.
* @param {Any} currVal The current value of the attribute
* @param {Any} newVal The new value of the attribute
* @param {Object} opts Any additional event data to mix into the attribute change event's event facade.
*/
_fireAttrChange : function(attrName, subAttrName, currVal, newVal, opts) {
var eventName = attrName + CHANGE,
conf = this._conf,
facade;
if (!conf.get(attrName, PUBLISHED)) {
var eventConfig = {
queuable:false,
defaultFn:this._defAttrChangeFn,
silent:true
};
eventConfig.broadcast = conf.get(attrName, BROADCAST);
this.publish(eventName, eventConfig);
conf.add(attrName, PUBLISHED, true);
}
facade = (opts) ? Y.merge(opts) : this._ATTR_E_FACADE;
facade.type = eventName;
facade.attrName = attrName;
facade.subAttrName = subAttrName;
facade.prevVal = currVal;
facade.newVal = newVal;
this.fire(facade);
},
/**
* Default handler implementation for Attribute change events
*
* @private
* @method _defAttrChangeFn
* @param {Event.Facade} e The event object for the custom event
*/
_defAttrChangeFn : function(e) {
if (!this._setAttrVal(e.attrName, e.subAttrName, e.prevVal, e.newVal)) {
Y.log('State not updated and stopImmediatePropagation called for attribute: ' + e.attrName + ' , value:' + e.newVal, 'warn', 'attribute');
// Prevent "after" listeners from being invoked since nothing changed.
e.stopImmediatePropagation();
} else {
e.newVal = this._conf.get(e.attrName, VALUE);
}
},
/**
* Updates the stored value of the attribute in the privately held State object,
* if validation and setter passes.
*
* @method _setAttrVal
* @private
* @param {String} attrName The attribute name.
* @param {String} subAttrName The sub-attribute name, if setting a sub-attribute property ("x.y.z").
* @param {Any} prevVal The currently stored value of the attribute.
* @param {Any} newVal The value which is going to be stored.
*
* @return {booolean} true if the new attribute value was stored, false if not.
*/
_setAttrVal : function(attrName, subAttrName, prevVal, newVal) {
var allowSet = true,
conf = this._conf,
validator = conf.get(attrName, VALIDATOR),
setter = conf.get(attrName, SETTER),
name = subAttrName || attrName,
retVal;
if (!validator || validator.call(this, newVal, name)) {
if (setter) {
retVal = setter.call(this, newVal, name);
if (retVal === INVALID_VALUE) {
Y.log('Attribute: ' + attrName + ', setter returned Attribute.INVALID_VALUE for value:' + newVal, 'warn', 'attribute');
allowSet = false;
} else if (retVal !== undefined){
Y.log('Attribute: ' + attrName + ', raw value: ' + newVal + ' modified by setter to:' + retVal, 'info', 'attribute');
newVal = retVal;
}
}
if (allowSet) {
if(!subAttrName && newVal === prevVal) {
Y.log('Attribute: ' + attrName + ', value unchanged:' + newVal, 'warn', 'attribute');
allowSet = false;
} else {
// Store value
if (conf.get(attrName, INIT_VALUE) === undefined) {
conf.add(attrName, INIT_VALUE, newVal);
}
conf.add(attrName, VALUE, newVal);
}
}
} else {
Y.log('Attribute:' + attrName + ', Validation failed for value:' + newVal, 'warn', 'attribute');
allowSet = false;
}
return allowSet;
},
/**
* Sets multiple attribute values.
*
* @method setAttrs
* @param {Object} attrs A hash of attributes: name/value pairs
* @chainable
*/
setAttrs : function(attrs) {
for (var attr in attrs) {
if ( attrs.hasOwnProperty(attr) ) {
this.set(attr, attrs[attr]);
}
}
return this;
},
/**
* Gets multiple attribute values.
*
* @method getAttrs
* @param {Array | Boolean} attrs Optional. An array of attribute names, whose values are required. If omitted, all attribute values are
* returned. If set to true, all attributes modified from their original values are returned.
* @return {Object} A hash of attributes: name/value pairs
*/
getAttrs : function(attrs) {
var o = {}, i, l, attr, val,
modifiedOnly = (attrs === true);
attrs = (attrs && !modifiedOnly) ? attrs : O.keys(this._conf.data[VALUE]);
for (i = 0, l = attrs.length; i < l; i++) {
// Go through get, to honor cloning/normalization
attr = attrs[i];
val = this.get(attr);
if (!modifiedOnly || this._conf.get(attr, VALUE) != this._conf.get(attr, INIT_VALUE)) {
o[attr] = this.get(attr);
}
}
return o;
},
/**
* Configures attributes, and sets initial values. This method does not
* isolate configuration object by merging/cloning. The caller is responsible for
* merging/cloning the configuration object when required.
*
* @method addAttrs
* @chainable
*
* @param {Object} cfgs Name/value hash of attribute configuration literals.
* @param {Object} values Name/value hash of initial values to apply. Values defined in the configuration hash will be over-written by the initial values hash unless read-only.
*/
addAttrs : function(cfgs, values) {
if (cfgs) {
var attr,
attrCfg,
value;
values = this._splitAttrVals(values);
for (attr in cfgs) {
if (cfgs.hasOwnProperty(attr)) {
// Not Merging. Caller is responsible for isolating configs
attrCfg = cfgs[attr];
// Handle simple, complex and user values, accounting for read-only
value = this._getAttrInitVal(attr, attrCfg, values);
if (value !== undefined) {
attrCfg.value = value;
}
this.addAttr(attr, attrCfg);
}
}
}
return this;
},
/**
* Utility to split out regular attribute values
* from complex attribute values, so that complex
* attributes can be keyed by top level attribute name.
*
* @method _splitAttrValues
* @param {Object} valueHash Name/value hash of initial values
*
* @return {Object} Object literal with 2 properties - "simple" and "complex",
* containing simple and complex attribute values respectively keyed
* by attribute the top level attribute name.
* @private
*/
_splitAttrVals : function(valueHash) {
var vals = {},
subvals = {},
path,
attr,
v, k;
for (k in valueHash) {
if (valueHash.hasOwnProperty(k)) {
if (k.indexOf(DOT) !== -1) {
path = k.split(DOT);
attr = path.shift();
v = subvals[attr] = subvals[attr] || [];
v[v.length] = {
path : path,
value: valueHash[k]
};
} else {
vals[k] = valueHash[k];
}
}
}
return { simple:vals, complex:subvals };
},
/**
* Returns the initial value of the given attribute from
* either the default configuration provided, or the
* over-ridden value if it exists in the initValues
* hash provided, if the attribute is not read-only.
*
* @param {String} attr Attribute name
* @param {Object} cfg Default attribute configuration object literal
* @param {Object} initValues Name/Value hash of initial attribute values from _splitAttrVals
*
* @return {Any} Initial value of the attribute.
*
* @method _getAttrInitVal
* @private
*/
_getAttrInitVal : function(attr, cfg, initValues) {
var val = (cfg.valueFn) ? cfg.valueFn.call(this) : cfg.value,
simple,
complex,
i,
l,
path,
subval,
subvals;
if (!cfg[READ_ONLY] && initValues) {
// Simple Attributes
simple = initValues.simple;
if (simple && simple.hasOwnProperty(attr)) {
val = simple[attr];
}
// Complex Attributes (complex values applied, after simple, incase both are set)
complex = initValues.complex;
if (complex && complex.hasOwnProperty(attr)) {
subvals = complex[attr];
for (i = 0, l = subvals.length; i < l; ++i) {
path = subvals[i].path;
subval = subvals[i].value;
O.setValue(val, path, subval);
}
}
}
return val;
}
};
// Basic prototype augment - no lazy constructor invocation.
Y.mix(Attribute, EventTarget, false, null, 1);
Y.Attribute = Attribute;