attribute-debug.js revision c4cf29edebef0d1c75ccfa55f67b2549c235bf8e
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam MooreYUI.add('attribute-base', function(Y) {
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * The State class maintains state for a collection of named items, with
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * a varying number of properties defined.
0a9c6f9f30a66e52ec4ea4ed93504580b3a5669aAdam Moore *
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * It avoids the need to create a separate class for the item, and separate instances
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * of these classes for each item, by storing the state in a 2 level hash table,
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * improving performance when the number of items is likely to be large.
0a9c6f9f30a66e52ec4ea4ed93504580b3a5669aAdam Moore *
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * @constructor
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @class State
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore */
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore Y.State = function() {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * Hash of attributes
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @property data
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore */
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore this.data = {};
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore };
9cdb1aa8d3a7901f789c2ad7a6ea00e804a9abebAdam Moore
9cdb1aa8d3a7901f789c2ad7a6ea00e804a9abebAdam Moore Y.State.prototype = {
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * Adds a property to an item.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @method add
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param name {String} The name of the item.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param key {String} The name of the property.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param val {Any} The value of the property.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore */
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore add : function(name, key, val) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore var d = this.data;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore d[key] = d[key] || {};
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore d[key][name] = val;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore },
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * Adds multiple properties to an item.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore *
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @method addAll
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @param name {String} The name of the item.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @param o {Object} A hash of property/value pairs.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore */
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore addAll: function(name, o) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore var key;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore for (key in o) {
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore if (o.hasOwnProperty(key)) {
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore this.add(name, key, o[key]);
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore }
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore }
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore },
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * Removes a property from an item.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @method remove
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param name {String} The name of the item.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param key {String} The property to remove.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore */
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore remove: function(name, key) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore var d = this.data;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore if (d[key] && (name in d[key])) {
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore delete d[key][name];
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore }
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore },
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore /**
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * Removes multiple properties from an item, or remove the item completely.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @method removeAll
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param name {String} The name of the item.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param o {Object|Array} Collection of properties to delete. If not provided, the entire item is removed.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore */
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore removeAll: function(name, o) {
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore var d = this.data;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore Y.each(o || d, function(v, k) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore if(Y.Lang.isString(k)) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore this.remove(name, k);
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore } else {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore this.remove(name, v);
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore }
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore }, this);
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore },
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * For a given item, returns the value of the property requested, or undefined if not found.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @method get
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @param name {String} The name of the item
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @param key {String} Optional. The property value to retrieve.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * @return {Any} The value of the supplied property.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore */
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore get: function(name, key) {
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore var d = this.data;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore return (d[key] && name in d[key]) ? d[key][name] : undefined;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore },
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore /**
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * For the given item, returns a disposable object with all of the
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * item's property/value pairs.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @method getAll
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @param name {String} The name of the item
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @return {Object} An object with property/value pairs for the item.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore */
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore getAll : function(name) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore var d = this.data, o;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore Y.each(d, function(v, k) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore if (name in d[k]) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore o = o || {};
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore o[k] = v[name];
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore }
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore }, this);
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore return o;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore }
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore };
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * The attribute module provides an augmentable Attribute implementation, which
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * adds configurable attributes and attribute change events to the class being
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * augmented. It also provides a State class, which is used internally by Attribute,
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * but can also be used independently to provide a name/property/value data structure to
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * store state.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @module attribute
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore */
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * The attribute-base submodule provides core attribute handling support, with everything
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * aside from complex attribute handling in the provider's constructor.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @module attribute
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @submodule attribute-base
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore */
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore var O = Y.Object,
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore Lang = Y.Lang,
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore EventTarget = Y.EventTarget,
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore DOT = ".",
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore CHANGE = "Change",
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore // Externally configurable props
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore GETTER = "getter",
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore SETTER = "setter",
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore READ_ONLY = "readOnly",
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore WRITE_ONCE = "writeOnce",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore INIT_ONLY = "initOnly",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore VALIDATOR = "validator",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore VALUE = "value",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore VALUE_FN = "valueFn",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore BROADCAST = "broadcast",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore LAZY_ADD = "lazyAdd",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore BYPASS_PROXY = "_bypassProxy",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore // Used for internal state management
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore ADDED = "added",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore INITIALIZING = "initializing",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore INIT_VALUE = "initValue",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore PUBLISHED = "published",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore DEF_VALUE = "defaultValue",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore LAZY = "lazy",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore IS_LAZY_ADD = "isLazyAdd",
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore INVALID_VALUE,
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore MODIFIABLE = {};
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore // Properties which can be changed after the attribute has been added.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore MODIFIABLE[READ_ONLY] = 1;
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore MODIFIABLE[WRITE_ONCE] = 1;
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore MODIFIABLE[GETTER] = 1;
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore MODIFIABLE[BROADCAST] = 1;
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * Attribute provides configurable attribute support along with attribute change events. It is designed to be
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * augmented on to a host class, and provides the host with the ability to configure attributes to store and retrieve state,
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * along with attribute change events.
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * </p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>For example, attributes added to the host can be configured:</p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <ul>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <li>As read only.</li>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <li>As write once.</li>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <li>With a setter function, which can be used to manipulate
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <li>With a getter function, which can be used to manipulate stored values,
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * before they are returned by Attribute's <a href="#method_get">get</a> method.</li>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <li>With a validator function, to validate values before they are stored.</li>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * </ul>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * options available for attributes</p>.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p><strong>NOTE:</strong> Most implementations will be better off extending the <a href="Base.html">Base</a> class,
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * of attributes for derived classes, accounting for values passed into the constructor.</p>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore *
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @class Attribute
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @uses EventTarget
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore */
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore function Attribute(attrs, values) {
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore var host = this; // help compression
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore // Perf tweak - avoid creating event literals if not required.
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore host._ATTR_E_FACADE = {};
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore EventTarget.call(host, {emitFacade:true});
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore // _conf maintained for backwards compat
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore host._conf = host._state = new Y.State();
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore host._stateProxy = host._stateProxy || null;
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore host._requireAddAttr = host._requireAddAttr || false;
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore this._initAttrs(attrs, values);
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore }
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore /**
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <p>The value to return from an attribute setter in order to prevent the set from going through.</p>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore *
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <p>You can return this value from your setter if you wish to combine validator and setter
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * functionality into a single setter function, which either returns the massaged value to be stored or
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * Attribute.INVALID_VALUE to prevent invalid values from being stored.</p>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore *
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @property Attribute.INVALID_VALUE
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @type Object
111837fe5c14f516f4a15878f9bbaf7bb0091364Adam Moore * @static
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @final
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore */
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore Attribute.INVALID_VALUE = {};
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore INVALID_VALUE = Attribute.INVALID_VALUE;
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore /**
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * The list of properties which can be configured for
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * each attribute (e.g. setter, getter, writeOnce etc.).
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore *
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * This property is used internally as a whitelist for faster
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * Y.mix operations.
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore *
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @property Attribute._ATTR_CFG
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @type Array
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @static
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * @protected
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore */
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore Attribute._ATTR_CFG = [SETTER, GETTER, VALIDATOR, VALUE, VALUE_FN, WRITE_ONCE, READ_ONLY, LAZY_ADD, BROADCAST, BYPASS_PROXY];
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore Attribute.prototype = {
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore /**
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <p>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * Adds an attribute with the provided configuration to the host object.
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * </p>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <p>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * The config argument object supports the following properties:
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * </p>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore *
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <dl>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <dt>value &#60;Any&#62;</dt>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <dd>The initial value to set on the attribute</dd>
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore *
d1f171a81a8b50c0f694f3dd1ea7ccc08e86cf55Adam Moore * <dt>valueFn &#60;Function | String&#62;</dt>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>A function, which will return the initial value to set on the attribute. This is useful
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * for cases where the attribute configuration is defined statically, but needs to
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * reference the host instance ("this") to obtain an initial value. If both the value and valueFn properties are defined,
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * the value returned by the valueFn has precedence over the value property, unless it returns undefined, in which
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * case the value property is used.</p>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore *
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * <p>valueFn can also be set to a string, representing the name of the instance method to be used to retrieve the value.</p>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * </dd>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dt>readOnly &#60;boolean&#62;</dt>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dd>Whether or not the attribute is read only. Attributes having readOnly set to true
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * cannot be modified by invoking the set method.</dd>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore *
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * <dt>writeOnce &#60;boolean&#62; or &#60;string&#62;</dt>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * Whether or not the attribute is "write once". Attributes having writeOnce set to true,
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * can only have their values set once, be it through the default configuration,
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * constructor configuration arguments, or by invoking set.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>The writeOnce attribute can also be set to the string "initOnly", in which case the attribute can only be set during initialization
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * (when used with Base, this means it can only be set during construction)</p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * </dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dt>setter &#60;Function | String&#62;</dt>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>The setter function used to massage or normalize the value passed to the set method for the attribute.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * The value returned by the setter will be the final stored value. Returning
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <a href="#property_Attribute.INVALID_VALUE">Attribute.INVALID_VALUE</a>, from the setter will prevent
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * the value from being stored.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * </p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>setter can also be set to a string, representing the name of the instance method to be used as the setter function.</p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * </dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dt>getter &#60;Function | String&#62;</dt>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * <dd>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * <p>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * The getter function used to massage or normalize the value returned by the get method for the attribute.
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * The value returned by the getter function is the value which will be returned to the user when they
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * invoke get.
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * </p>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>getter can also be set to a string, representing the name of the instance method to be used as the getter function.</p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * </dd>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore *
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * <dt>validator &#60;Function | String&#62;</dt>
6a3faa9e0e4639febffbd7018ce47b861626d0baAdam Moore * <dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * The validator function invoked prior to setting the stored value. Returning
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * false from the validator function will prevent the value from being stored.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * </p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>validator can also be set to a string, representing the name of the instance method to be used as the validator function.</p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * </dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dt>broadcast &#60;int&#62;</dt>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dd>If and how attribute change events for this attribute should be broadcast. See CustomEvent's <a href="CustomEvent.html#property_broadcast">broadcast</a> property for
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * valid values. By default attribute change events are not broadcast.</dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dt>lazyAdd &#60;boolean&#62;</dt>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <dd>Whether or not to delay initialization of the attribute until the first call to get/set it.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * the <a href="#method_addAttrs">addAttrs</a> method.</dd>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore * </dl>
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore *
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore * <p>The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore * the context ("this") set to the host object.</p>
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore *
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore * <p>Configuration properties outside of the list mentioned above are considered private properties used internally by attribute, and are not intended for public use.</p>
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore *
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore * @method addAttr
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore *
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore * @param {String} name The name of the attribute.
df39d9c816a02c79aa6a3436784de5bba0ef7075Adam Moore * @param {Object} config An object with attribute configuration property/value pairs, specifying the configuration for the attribute.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * <strong>NOTE:</strong> The configuration object is modified when adding an attribute, so if you need
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore * to protect the original values, you will need to merge the object.
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore * </p>
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore *
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore * @param {boolean} lazy (optional) Whether or not to add this attribute lazily (on the first call to get/set).
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore *
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore * @return {Object} A reference to the host object.
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore *
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore * @chainable
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore */
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore addAttr: function(name, config, lazy) {
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore Y.log('Adding attribute: ' + name, 'info', 'attribute');
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore var host = this, // help compression
03f9aefec605c500b64625110a955e65b900b100Adam Moore state = host._state,
03f9aefec605c500b64625110a955e65b900b100Adam Moore value,
03f9aefec605c500b64625110a955e65b900b100Adam Moore hasValue;
03f9aefec605c500b64625110a955e65b900b100Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore lazy = (LAZY_ADD in config) ? config[LAZY_ADD] : lazy;
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore if (lazy && !host.attrAdded(name)) {
03f9aefec605c500b64625110a955e65b900b100Adam Moore state.add(name, LAZY, config || {});
03f9aefec605c500b64625110a955e65b900b100Adam Moore state.add(name, ADDED, true);
03f9aefec605c500b64625110a955e65b900b100Adam Moore } else {
03f9aefec605c500b64625110a955e65b900b100Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore if (host.attrAdded(name) && !state.get(name, IS_LAZY_ADD)) { Y.log('Attribute: ' + name + ' already exists. Cannot add it again without removing it first', 'warn', 'attribute'); }
03f9aefec605c500b64625110a955e65b900b100Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore if (!host.attrAdded(name) || state.get(name, IS_LAZY_ADD)) {
03f9aefec605c500b64625110a955e65b900b100Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore config = config || {};
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore hasValue = (VALUE in config);
03f9aefec605c500b64625110a955e65b900b100Adam Moore
f89b4dd628000da1b003539c3c181e6b9880de00Adam Moore if (config.readOnly && !hasValue) { Y.log('readOnly attribute: ' + name + ', added without an initial value. Value will be set on initial call to set', 'warn', 'attribute');}
f89b4dd628000da1b003539c3c181e6b9880de00Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore if(hasValue) {
2f03ba9e07559709925bfe6cb1b40c83aa810672Adam Moore // We'll go through set, don't want to set value in config directly
f89b4dd628000da1b003539c3c181e6b9880de00Adam Moore value = config.value;
f89b4dd628000da1b003539c3c181e6b9880de00Adam Moore delete config.value;
f89b4dd628000da1b003539c3c181e6b9880de00Adam Moore }
f89b4dd628000da1b003539c3c181e6b9880de00Adam Moore
03f9aefec605c500b64625110a955e65b900b100Adam Moore config.added = true;
f89b4dd628000da1b003539c3c181e6b9880de00Adam Moore config.initializing = true;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore state.addAll(name, config);
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore if (hasValue) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore // Go through set, so that raw values get normalized/validated
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore host.set(name, value);
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore state.remove(name, INITIALIZING);
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore return host;
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore },
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore /**
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * Checks if the given attribute has been added to the host
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @method attrAdded
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * @param {String} name The name of the attribute to check.
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * @return {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.
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore */
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore attrAdded: function(name) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore return !!this._state.get(name, ADDED);
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore },
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore /**
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * Updates the configuration of an attribute which has already been added.
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * <p>
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * The properties which can be modified through this interface are limited
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * to the following subset of attributes, which can be safely modified
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * after a value has already been set on the attribute: readOnly, writeOnce,
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * broadcast and getter.
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * </p>
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * @method modifyAttr
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * @param {String} name The name of the attribute whose configuration is to be updated.
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * @param {Object} config An object with configuration property/value pairs, specifying the configuration properties to modify.
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore */
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore modifyAttr: function(name, config) {
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore var host = this, // help compression
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore prop, state;
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore if (host.attrAdded(name)) {
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore if (host._isLazyAttr(name)) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore host._addLazyAttr(name);
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore state = host._state;
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore for (prop in config) {
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore if (MODIFIABLE[prop] && config.hasOwnProperty(prop)) {
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore state.add(name, prop, config[prop]);
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore // If we reconfigured broadcast, need to republish
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore if (prop === BROADCAST) {
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore state.remove(name, PUBLISHED);
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore }
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore if (!host.attrAdded(name)) {Y.log('Attribute modifyAttr:' + name + ' has not been added. Use addAttr to add the attribute', 'warn', 'attribute');}
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore },
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore /**
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * Removes an attribute from the host object
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore *
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @method removeAttr
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @param {String} name The name of the attribute to be removed.
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore */
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore removeAttr: function(name) {
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore this._state.removeAll(name);
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore },
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore /**
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * Returns the current value of the attribute. If the attribute
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * has been configured with a 'getter' function, this method will delegate
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * to the 'getter' to obtain the value of the attribute.
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore *
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @method get
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore *
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @param {String} name The name of the attribute. If the value of the attribute is an Object,
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * dot notation can be used to obtain the value of a property of the object (e.g. <code>get("x.y.z")</code>)
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore *
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @return {Any} The value of the attribute
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore */
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore get : function(name) {
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore return this._getAttr(name);
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore },
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore /**
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * Checks whether or not the attribute is one which has been
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * added lazily and still requires initialization.
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore *
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @method _isLazyAttr
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @private
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @param {String} name The name of the attribute
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * @return {boolean} true if it's a lazily added attribute, false otherwise.
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore */
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore _isLazyAttr: function(name) {
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore return this._state.get(name, LAZY);
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore },
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore /**
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * Finishes initializing an attribute which has been lazily added.
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore *
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * @method _addLazyAttr
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * @private
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * @param {Object} name The name of the attribute
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore */
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore _addLazyAttr: function(name) {
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore var state = this._state,
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore lazyCfg = state.get(name, LAZY);
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore state.add(name, IS_LAZY_ADD, true);
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore state.remove(name, LAZY);
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore this.addAttr(name, lazyCfg);
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore },
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore /**
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * Sets the value of an attribute.
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore *
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * @method set
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * @chainable
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore *
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * @param {String} name The name of the attribute. If the
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * current value of the attribute is an Object, dot notation can be used
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * to set the value of a property within the object (e.g. <code>set("x.y.z", 5)</code>).
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore *
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore * @param {Any} value The value to set the attribute to.
38ede344a04d04daedd560a485bd38f50e4c0a71Adam Moore *
bc8660dcb747bedc141ca9061de83f6f32f8018fAdam Moore * @param {Object} opts (Optional) Optional event data to be mixed into
5cbcc8e7f5c3e4ad283e5cb76520840300f81a0aAdam Moore * the event facade passed to subscribers of the attribute's change event. This
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * can be used as a flexible way to identify the source of a call to set, allowing
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * the developer to distinguish between set called internally by the host, vs.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * set called externally by the application developer.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore *
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore * @return {Object} A reference to the host object.
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore */
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore set : function(name, val, opts) {
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore return this._setAttr(name, val, opts);
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore },
3641f0baf10c9737e4ac6aac1566bfeaca00eeffAdam Moore
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore /**
e69255aa5a65f8406ba2fabaf69fe4e1d05daf69Adam Moore * Resets the attribute (or all attributes) to its initial value, as long as
* the attribute is not readOnly, or writeOnce.
*
* @method reset
* @param {String} name Optional. The name of the attribute to reset. If omitted, all attributes are reset.
* @return {Object} A reference to the host object.
* @chainable
*/
reset : function(name) {
var host = this, // help compression
added;
if (name) {
if (host._isLazyAttr(name)) {
host._addLazyAttr(name);
}
host.set(name, host._state.get(name, INIT_VALUE));
} else {
added = host._state.data.added;
Y.each(added, function(v, n) {
host.reset(n);
}, host);
}
return host;
},
/**
* Allows setting of readOnly/writeOnce attributes. See <a href="#method_set">set</a> for argument details.
*
* @method _set
* @protected
* @chainable
*
* @param {String} name The name of the attribute.
* @param {Any} val The value to set the attribute to.
* @param {Object} opts (Optional) Optional event data to be mixed into
* the event facade passed to subscribers of the attribute's change event.
* @return {Object} A reference to the host object.
*/
_set : function(name, val, opts) {
return this._setAttr(name, val, opts, true);
},
/**
* Provides the common implementation for the public get method,
* allowing Attribute hosts to over-ride either method.
*
* See <a href="#method_get">get</a> for argument details.
*
* @method _getAttr
* @protected
* @chainable
*
* @param {String} name The name of the attribute.
* @return {Any} The value of the attribute.
*/
_getAttr : function(name) {
var host = this, // help compression
fullName = name,
state = host._state,
path,
getter,
val,
cfg;
if (name.indexOf(DOT) !== -1) {
path = name.split(DOT);
name = path.shift();
}
// On Demand - Should be rare - handles out of order valueFn references
if (host._tCfgs && host._tCfgs[name]) {
cfg = {};
cfg[name] = host._tCfgs[name];
delete host._tCfgs[name];
host._addAttrs(cfg, host._tVals);
}
// Lazy Init
if (host._isLazyAttr(name)) {
host._addLazyAttr(name);
}
val = host._getStateVal(name);
getter = state.get(name, GETTER);
if (getter && !getter.call) {
getter = this[getter];
}
val = (getter) ? getter.call(host, val, fullName) : val;
val = (path) ? O.getValue(val, path) : val;
return val;
},
/**
* Provides the common implementation for the public set and protected _set methods.
*
* See <a href="#method_set">set</a> for argument details.
*
* @method _setAttr
* @protected
* @chainable
*
* @param {String} name The name of the attribute.
* @param {Any} value The value to set the attribute to.
* @param {Object} opts (Optional) Optional event data to be mixed into
* the event facade passed to subscribers of the attribute's change event.
* @param {boolean} force If true, allows the caller to set values for
* readOnly or writeOnce attributes which have already been set.
*
* @return {Object} A reference to the host object.
*/
_setAttr : function(name, val, opts, force) {
var allowSet = true,
state = this._state,
stateProxy = this._stateProxy,
data = state.data,
initialSet,
strPath,
path,
currVal,
writeOnce,
initializing;
if (name.indexOf(DOT) !== -1) {
strPath = name;
path = name.split(DOT);
name = path.shift();
}
if (this._isLazyAttr(name)) {
this._addLazyAttr(name);
}
initialSet = (!data.value || !(name in data.value));
if (stateProxy && name in stateProxy && !this._state.get(name, BYPASS_PROXY)) {
// TODO: Value is always set for proxy. Can we do any better? Maybe take a snapshot as the initial value for the first call to set?
initialSet = false;
}
if (this._requireAddAttr && !this.attrAdded(name)) {
Y.log('Set attribute:' + name + ', aborted; Attribute is not configured', 'warn', 'attribute');
} else {
writeOnce = state.get(name, WRITE_ONCE);
initializing = state.get(name, INITIALIZING);
if (!initialSet && !force) {
if (writeOnce) {
Y.log('Set attribute:' + name + ', aborted; Attribute is writeOnce', 'warn', 'attribute');
allowSet = false;
}
if (state.get(name, READ_ONLY)) {
Y.log('Set attribute:' + name + ', aborted; Attribute is readOnly', 'warn', 'attribute');
allowSet = false;
}
}
if (!initializing && !force && writeOnce === INIT_ONLY) {
Y.log('Set attribute:' + name + ', aborted; Attribute is writeOnce: "initOnly"', 'warn', 'attribute');
allowSet = false;
}
if (allowSet) {
// Don't need currVal if initialSet (might fail in custom getter if it always expects a non-undefined/non-null value)
if (!initialSet) {
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 (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 host = this,
eventName = attrName + CHANGE,
state = host._state,
facade;
if (!state.get(attrName, PUBLISHED)) {
host.publish(eventName, {
queuable:false,
defaultTargetOnly: true,
defaultFn:host._defAttrChangeFn,
silent:true,
broadcast : state.get(attrName, BROADCAST)
});
state.add(attrName, PUBLISHED, true);
}
facade = (opts) ? Y.merge(opts) : host._ATTR_E_FACADE;
// Not using the single object signature for fire({type:..., newVal:...}), since
// we don't want to override type. Changed to the fire(type, {newVal:...}) signature.
// facade.type = eventName;
facade.attrName = attrName;
facade.subAttrName = subAttrName;
facade.prevVal = currVal;
facade.newVal = newVal;
// host.fire(facade);
host.fire(eventName, facade);
},
/**
* Default function for attribute change events.
*
* @private
* @method _defAttrChangeFn
* @param {EventFacade} e The event object for attribute change events.
*/
_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.get(e.attrName);
}
},
/**
* Gets the stored value for the attribute, from either the
* internal state object, or the state proxy if it exits
*
* @method _getStateVal
* @private
* @param {String} name The name of the attribute
* @return {Any} The stored value of the attribute
*/
_getStateVal : function(name) {
var stateProxy = this._stateProxy;
return stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY) ? stateProxy[name] : this._state.get(name, VALUE);
},
/**
* Sets the stored value for the attribute, in either the
* internal state object, or the state proxy if it exits
*
* @method _setStateVal
* @private
* @param {String} name The name of the attribute
* @param {Any} value The value of the attribute
*/
_setStateVal : function(name, value) {
var stateProxy = this._stateProxy;
if (stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY)) {
stateProxy[name] = value;
} else {
this._state.add(name, VALUE, 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 host = this,
allowSet = true,
state = host._state,
validator = state.get(attrName, VALIDATOR),
setter = state.get(attrName, SETTER),
initializing = state.get(attrName, INITIALIZING),
prevValRaw = this._getStateVal(attrName),
name = subAttrName || attrName,
retVal,
valid;
if (validator) {
if (!validator.call) {
// Assume string - trying to keep critical path tight, so avoiding Lang check
validator = this[validator];
}
if (validator) {
valid = validator.call(host, newVal, name);
if (!valid && initializing) {
newVal = state.get(attrName, DEF_VALUE);
valid = true; // Assume it's valid, for perf.
}
}
}
if (!validator || valid) {
if (setter) {
if (!setter.call) {
// Assume string - trying to keep critical path tight, so avoiding Lang check
setter = this[setter];
}
if (setter) {
retVal = setter.call(host, 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 === prevValRaw) && !Lang.isObject(newVal)) {
Y.log('Attribute: ' + attrName + ', value unchanged:' + newVal, 'warn', 'attribute');
allowSet = false;
} else {
// Store value
if (state.get(attrName, INIT_VALUE) === undefined) {
state.add(attrName, INIT_VALUE, newVal);
}
host._setStateVal(attrName, 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 An object with attributes name/value pairs.
* @return {Object} A reference to the host object.
* @chainable
*/
setAttrs : function(attrs, opts) {
return this._setAttrs(attrs, opts);
},
/**
* Implementation behind the public setAttrs method, to set multiple attribute values.
*
* @method _setAttrs
* @protected
* @param {Object} attrs An object with attributes name/value pairs.
* @return {Object} A reference to the host object.
* @chainable
*/
_setAttrs : function(attrs, opts) {
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. If omitted, all attribute values are
* returned. If set to true, all attributes modified from their initial values are returned.
* @return {Object} An object with attribute name/value pairs.
*/
getAttrs : function(attrs) {
return this._getAttrs(attrs);
},
/**
* Implementation behind the public getAttrs method, to get multiple attribute values.
*
* @method _getAttrs
* @protected
* @param {Array | boolean} attrs 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.
* @return {Object} An object with attribute name/value pairs.
*/
_getAttrs : function(attrs) {
var host = this,
o = {},
i, l, attr, val,
modifiedOnly = (attrs === true);
attrs = (attrs && !modifiedOnly) ? attrs : O.keys(host._state.data.added);
for (i = 0, l = attrs.length; i < l; i++) {
// Go through get, to honor cloning/normalization
attr = attrs[i];
val = host.get(attr);
if (!modifiedOnly || host._getStateVal(attr) != host._state.get(attr, INIT_VALUE)) {
o[attr] = host.get(attr);
}
}
return o;
},
/**
* Configures a group of attributes, and sets initial values.
*
* <p>
* <strong>NOTE:</strong> This method does not isolate the configuration object by merging/cloning.
* The caller is responsible for merging/cloning the configuration object if required.
* </p>
*
* @method addAttrs
* @chainable
*
* @param {Object} cfgs An object with attribute name/configuration pairs.
* @param {Object} values 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.
* @param {boolean} lazy 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 <a href="#method_addAttr">addAttr</a>.
*
* @return {Object} A reference to the host object.
*/
addAttrs : function(cfgs, values, lazy) {
var host = this; // help compression
if (cfgs) {
host._tCfgs = cfgs;
host._tVals = host._normAttrVals(values);
host._addAttrs(cfgs, host._tVals, lazy);
host._tCfgs = host._tVals = null;
}
return host;
},
/**
* 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).
*
* @method _addAttrs
* @private
* @param {Object} cfgs An object with attribute name/configuration pairs.
* @param {Object} values 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.
* @param {boolean} lazy 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 <a href="#method_addAttr">addAttr</a>.
*/
_addAttrs : function(cfgs, values, lazy) {
var host = this, // help compression
attr,
attrCfg,
value;
for (attr in cfgs) {
if (cfgs.hasOwnProperty(attr)) {
// Not Merging. Caller is responsible for isolating configs
attrCfg = cfgs[attr];
attrCfg.defaultValue = attrCfg.value;
// Handle simple, complex and user values, accounting for read-only
value = host._getAttrInitVal(attr, attrCfg, host._tVals);
if (value !== undefined) {
attrCfg.value = value;
}
if (host._tCfgs[attr]) {
delete host._tCfgs[attr];
}
host.addAttr(attr, attrCfg, lazy);
}
}
},
/**
* Utility method to protect an attribute configuration
* hash, by merging the entire object and the individual
* attr config objects.
*
* @method _protectAttrs
* @protected
* @param {Object} attrs A hash of attribute to configuration object pairs.
* @return {Object} A protected version of the attrs argument.
*/
_protectAttrs : function(attrs) {
if (attrs) {
attrs = Y.merge(attrs);
for (var attr in attrs) {
if (attrs.hasOwnProperty(attr)) {
attrs[attr] = Y.merge(attrs[attr]);
}
}
}
return attrs;
},
/**
* Utility method to normalize attribute values. The base implementation
* simply merges the hash to protect the original.
*
* @method _normAttrVals
* @param {Object} valueHash An object with attribute name/value pairs
*
* @return {Object}
*
* @private
*/
_normAttrVals : function(valueHash) {
return (valueHash) ? Y.merge(valueHash) : null;
},
/**
* 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.
*
* @param {String} attr The name of the attribute
* @param {Object} cfg The attribute configuration object
* @param {Object} initValues The object with simple and complex attribute name/value pairs returned from _normAttrVals
*
* @return {Any} The initial value of the attribute.
*
* @method _getAttrInitVal
* @private
*/
_getAttrInitVal : function(attr, cfg, initValues) {
var val, valFn;
// init value is provided by the user if it exists, else, provided by the config
if (!cfg[READ_ONLY] && initValues && initValues.hasOwnProperty(attr)) {
val = initValues[attr];
} else {
val = cfg[VALUE];
valFn = cfg[VALUE_FN];
if (valFn) {
if (!valFn.call) {
valFn = this[valFn];
}
if (valFn) {
val = valFn.call(this);
}
}
}
Y.log('initValue for ' + attr + ':' + val, 'info', 'attribute');
return val;
},
/**
* Returns an object with the configuration properties (and value)
* for the given attrubute. If attrName is not provided, returns the
* configuration properties for all attributes.
*
* @method _getAttrCfg
* @protected
* @param {String} name Optional. The attribute name. If not provided, the method will return the configuration for all attributes.
* @return {Object} The configuration properties for the given attribute, or all attributes.
*/
_getAttrCfg : function(name) {
var o,
data = this._state.data;
if (data) {
o = {};
Y.each(data, function(cfg, cfgProp) {
if (name) {
if(name in cfg) {
o[cfgProp] = cfg[name];
}
} else {
Y.each(cfg, function(attrCfg, attr) {
o[attr] = o[attr] || {};
o[attr][cfgProp] = attrCfg;
});
}
});
}
return o;
},
/**
* Utility method to set up initial attributes defined during construction, either through the constructor.ATTRS property, or explicitly passed in.
*
* @method _initAttrs
* @protected
* @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
* @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
*/
_initAttrs : function(attrs, values) {
// ATTRS support for Node, which is not Base based
attrs = attrs || this.constructor.ATTRS;
var Base = Y.Base;
if ( attrs && !(Base && Y.instanceOf(this, Base))) {
this.addAttrs(this._protectAttrs(attrs), values);
}
}
};
// Basic prototype augment - no lazy constructor invocation.
Y.mix(Attribute, EventTarget, false, null, 1);
Y.Attribute = Attribute;
}, '@VERSION@' ,{requires:['event-custom']});
YUI.add('attribute-complex', function(Y) {
/**
* Adds support for attribute providers to handle complex attributes in the constructor
*
* @module attribute
* @submodule attribute-complex
* @for Attribute
*/
var O = Y.Object,
DOT = ".";
Y.Attribute.Complex = function() {};
Y.Attribute.Complex.prototype = {
/**
* Utility method to split out simple attribute name/value pairs ("x")
* from complex attribute name/value pairs ("x.y.z"), so that complex
* attributes can be keyed by the top level attribute name.
*
* @method _normAttrVals
* @param {Object} valueHash An object with attribute name/value pairs
*
* @return {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.
*
* @private
*/
_normAttrVals : function(valueHash) {
var vals = {},
subvals = {},
path,
attr,
v, k;
if (valueHash) {
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 };
} else {
return null;
}
},
/**
* 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.
*
* @param {String} attr The name of the attribute
* @param {Object} cfg The attribute configuration object
* @param {Object} initValues The object with simple and complex attribute name/value pairs returned from _normAttrVals
*
* @return {Any} The initial value of the attribute.
*
* @method _getAttrInitVal
* @private
*/
_getAttrInitVal : function(attr, cfg, initValues) {
var val = cfg.value,
valFn = cfg.valueFn,
simple,
complex,
i,
l,
path,
subval,
subvals;
if (valFn) {
if (!valFn.call) {
valFn = this[valFn];
}
if (valFn) {
val = valFn.call(this);
}
}
if (!cfg.readOnly && 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;
}
};
Y.mix(Y.Attribute, Y.Attribute.Complex, true, null, 1);
}, '@VERSION@' ,{requires:['attribute-base']});
YUI.add('attribute', function(Y){}, '@VERSION@' ,{use:['attribute-base', 'attribute-complex']});