aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The attribute module provides an augmentable Attribute implementation, which
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * adds configurable attributes and attribute change events to the class being
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * augmented. It also provides a State class, which is used internally by Attribute,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * but can also be used independently to provide a name/property/value data structure to
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * store state.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @module attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * The attribute-events submodule provides augmentable attribute change event support
973e2309557e11c2dda6a3f764a503398ac26272Satyen Desai * for AttributeCore based implementations.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @module attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @submodule attribute-events
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Provides an augmentable implementation of attribute change events for
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * AttributeCore.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @class AttributeEvents
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @uses EventTarget
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Perf tweak - avoid creating event literals if not required.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Sets the value of an attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method set
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute. If the
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * current value of the attribute is an Object, dot notation can be used
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * to set the value of a property within the object (e.g. <code>set("x.y.z", 5)</code>).
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} value The value to set the attribute to.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} opts (Optional) Optional event data to be mixed into
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the event facade passed to subscribers of the attribute's change event. This
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * can be used as a flexible way to identify the source of a call to set, allowing
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the developer to distinguish between set called internally by the host, vs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * set called externally by the application developer.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Allows setting of readOnly/writeOnce attributes. See <a href="#method_set">set</a> for argument details.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _set
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @protected
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} name The name of the attribute.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} val The value to set the attribute to.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} opts (Optional) Optional event data to be mixed into
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * the event facade passed to subscribers of the attribute's change event.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Sets multiple attribute values.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method setAttrs
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} attrs An object with attributes name/value pairs.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @return {Object} A reference to the host object.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @chainable
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Utility method to help setup the event payload and fire the attribute change event.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _fireAttrChange
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} attrName The name of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {String} subAttrName The full path of the property being changed,
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * if this is a sub-attribute value being change. Otherwise null.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} currVal The current value of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Any} newVal The new value of the attribute
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {Object} opts Any additional event data to mix into the attribute change event's event facade.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai _fireAttrChange : function(attrName, subAttrName, currVal, newVal, opts) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai facade = (opts) ? Y.merge(opts) : host._ATTR_E_FACADE;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Not using the single object signature for fire({type:..., newVal:...}), since
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // we don't want to override type. Changed to the fire(type, {newVal:...}) signature.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // facade.type = eventName;
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // host.fire(facade);
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * Default function for attribute change events.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @method _defAttrChangeFn
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai * @param {EventFacade} e The event object for attribute change events.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai _defAttrChangeFn : function(e) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai if (!this._setAttrVal(e.attrName, e.subAttrName, e.prevVal, e.newVal)) {
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.log('State not updated and stopImmediatePropagation called for attribute: ' + e.attrName + ' , value:' + e.newVal, 'warn', 'attribute');
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Prevent "after" listeners from being invoked since nothing changed.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai // Basic prototype augment - no lazy constructor invocation.
aa3181942968bcffcfc221a75d8bdc38c4c19b4bSatyen Desai Y.mix(AttributeEvents, EventTarget, false, null, 1);