API Docs for: 3.18.1
Show:

File: attribute/js/AttributeExtras.js

  1. /**
  2. * The attribute module provides an augmentable Attribute implementation, which
  3. * adds configurable attributes and attribute change events to the class being
  4. * augmented. It also provides a State class, which is used internally by Attribute,
  5. * but can also be used independently to provide a name/property/value data structure to
  6. * store state.
  7. *
  8. * @module attribute
  9. */
  10.  
  11. /**
  12. * The attribute-extras submodule provides less commonly used attribute methods, and can
  13. * be augmented/mixed into an implemention which used attribute-core.
  14. *
  15. * @module attribute
  16. * @submodule attribute-extras
  17. */
  18. var BROADCAST = "broadcast",
  19. PUBLISHED = "published",
  20. INIT_VALUE = "initValue",
  21.  
  22. MODIFIABLE = {
  23. readOnly:1,
  24. writeOnce:1,
  25. getter:1,
  26. broadcast:1
  27. };
  28.  
  29. /**
  30. * A augmentable implementation for AttributeCore, providing less frequently used
  31. * methods for Attribute management such as modifyAttrs(), removeAttr and reset()
  32. *
  33. * @class AttributeExtras
  34. * @extensionfor AttributeCore
  35. */
  36. function AttributeExtras() {}
  37.  
  38. AttributeExtras.prototype = {
  39.  
  40. /**
  41. * Updates the configuration of an attribute which has already been added.
  42. * <p>
  43. * The properties which can be modified through this interface are limited
  44. * to the following subset of attributes, which can be safely modified
  45. * after a value has already been set on the attribute:
  46. * </p>
  47. * <dl>
  48. * <dt>readOnly;</dt>
  49. * <dt>writeOnce;</dt>
  50. * <dt>broadcast; and</dt>
  51. * <dt>getter.</dt>
  52. * </dl>
  53. * <p>
  54. * Note: New attributes cannot be added using this interface. New attributes must be
  55. * added using {{#crossLink "AttributeCore/addAttr:method"}}addAttr{{/crossLink}}, or an
  56. * appropriate manner for a class which utilises Attributes (e.g. the
  57. * {{#crossLink "Base/ATTRS:property"}}ATTRS{{/crossLink}} property in
  58. * {{#crossLink "Base"}}Base{{/crossLink}}).
  59. * </p>
  60. * @method modifyAttr
  61. * @param {String} name The name of the attribute whose configuration is to be updated.
  62. * @param {Object} config An object with configuration property/value pairs, specifying the configuration properties to modify.
  63. */
  64. modifyAttr: function(name, config) {
  65. var host = this, // help compression
  66. prop, state;
  67.  
  68. if (host.attrAdded(name)) {
  69.  
  70. if (host._isLazyAttr(name)) {
  71. host._addLazyAttr(name);
  72. }
  73.  
  74. state = host._state;
  75. for (prop in config) {
  76. if (MODIFIABLE[prop] && config.hasOwnProperty(prop)) {
  77. state.add(name, prop, config[prop]);
  78.  
  79. // If we reconfigured broadcast, need to republish
  80. if (prop === BROADCAST) {
  81. state.remove(name, PUBLISHED);
  82. }
  83. }
  84. }
  85. } else {
  86. Y.log('Attribute modifyAttr:' + name + ' has not been added. Use addAttr to add the attribute', 'warn', 'attribute');
  87. }
  88. },
  89.  
  90. /**
  91. * Removes an attribute from the host object
  92. *
  93. * @method removeAttr
  94. * @param {String} name The name of the attribute to be removed.
  95. */
  96. removeAttr: function(name) {
  97. this._state.removeAll(name);
  98. },
  99.  
  100. /**
  101. * Resets the attribute (or all attributes) to its initial value, as long as
  102. * the attribute is not readOnly, or writeOnce.
  103. *
  104. * @method reset
  105. * @param {String} name Optional. The name of the attribute to reset. If omitted, all attributes are reset.
  106. * @return {Object} A reference to the host object.
  107. * @chainable
  108. */
  109. reset : function(name) {
  110. var host = this; // help compression
  111.  
  112. if (name) {
  113. if (host._isLazyAttr(name)) {
  114. host._addLazyAttr(name);
  115. }
  116. host.set(name, host._state.get(name, INIT_VALUE));
  117. } else {
  118. Y.Object.each(host._state.data, function(v, n) {
  119. host.reset(n);
  120. });
  121. }
  122. return host;
  123. },
  124.  
  125. /**
  126. * Returns an object with the configuration properties (and value)
  127. * for the given attribute. If attrName is not provided, returns the
  128. * configuration properties for all attributes.
  129. *
  130. * @method _getAttrCfg
  131. * @protected
  132. * @param {String} name Optional. The attribute name. If not provided, the method will return the configuration for all attributes.
  133. * @return {Object} The configuration properties for the given attribute, or all attributes.
  134. */
  135. _getAttrCfg : function(name) {
  136. var o,
  137. state = this._state;
  138.  
  139. if (name) {
  140. o = state.getAll(name) || {};
  141. } else {
  142. o = {};
  143. Y.each(state.data, function(v, n) {
  144. o[n] = state.getAll(n);
  145. });
  146. }
  147.  
  148. return o;
  149. }
  150. };
  151.  
  152. Y.AttributeExtras = AttributeExtras;
  153.