Source: delite/Invalidating.js

  1. /** @module delite/Invalidating */
  2. define(["dcl/dcl", "dojo/_base/lang", "./Stateful"], function (dcl, lang, Stateful) {
  4. 	/**
  5. 	 * Mixin for classes (usually widgets) that watch a set of invalidating properties.
  6. 	 * @class module:delite/Invalidating
  7. 	 * @augments {module:delite/Stateful}
  8. 	 * @mixin
  9. 	 */
  10. 	return dcl(Stateful, /** @lends module:delite/Invalidating# */{
  11. 		// summary:
  12. 		//		Mixin for classes (usually widgets) that watch a set of invalidating properties
  13. 		//		and delay to the next execution frame the refresh following the changes of
  14. 		//		the values of these properties. The receiving class must extend delite/Widget
  15. 		//		or dojo/Evented.
  16. 		// description:
  17. 		//		Once a set of properties have been declared subject to invalidation using the method
  18. 		//		addInvalidatingProperties(), changes of the values of these properties possibly
  19. 		//		end up calling refreshProperties() and in all cases refreshRendering(),
  20. 		//		thus allowing the receiving class to refresh itself based on the new values.
  22. 		_renderHandle: null,
  24. 		// _invalidatingProperties: [private] Object
  25. 		//		A hash of properties to watch in order to trigger the invalidation of these properties
  26. 		//		and/or the rendering invalidation.
  27. 		//		This list must be initialized by the time buildRendering() completes, usually in preCreate(),
  28. 		//		using addInvalidatingProperties(). Default value is null.
  29. 		_invalidatingProperties: null,
  30. 		
  31. 		// _invalidatedProperties: [private] Object
  32. 		//		A hash of invalidated properties either to refresh them or to refresh the rendering.
  33. 		_invalidatedProperties: null,
  34. 		
  35. 		// invalidProperties: Boolean
  36. 		//		Whether at least one property is invalid. This is readonly information, one must call
  37. 		//		invalidateProperties() to modify this flag.
  38. 		
  39. 		/**
  40. 		 * Whether at least one property is invalid. This is readonly information, one must call
  41. 		 * invalidateProperties() to modify this flag.
  42. 		 * @member {boolean}
  43. 		 * @default false
  44. 		 */
  45. 		invalidProperties: false,
  46. 		
  47. 		// invalidRenderering: Boolean
  48. 		//		Whether the rendering is invalid. This is readonly information, one must call
  49. 		//		invalidateRendering() to modify this flag.
  50. 		
  51. 		/**
  52. 		 * Whether the rendering is invalid. This is readonly information, one must call
  53. 		 * invalidateRendering() to modify this flag.
  54. 		 * @member {boolean}
  55. 		 * @default false
  56. 		 */
  57. 		invalidRendering: false,
  59. 		// if we are not a Widget, setup the listeners at construction time
  60. 		constructor: dcl.after(function () {
  61. 			this._initializeInvalidating();
  62. 		}),
  64. 		// if we are on a Widget, listen for any changes to properties after the widget has been rendered,
  65. 		// including when declarative properties (ex: iconClass=xyz) are applied.
  66. 		buildRendering: dcl.after(function () {
  67. 			// tags:
  68. 			//		protected
  69. 			this._initializeInvalidating();
  70. 		}),
  72. 		_initializeInvalidating: function () {
  73. 			if (this._invalidatingProperties) {
  74. 				var props = Object.keys(this._invalidatingProperties);
  75. 				for (var i = 0; i < props.length; i++) {
  76. 					this.watch(props[i], lang.hitch(this, this._invalidatingProperties[props[i]]));
  77. 				}
  78. 			}
  79. 			this._invalidatedProperties = {};
  80. 		},
  82. 		/**
  83. 		 * Adds the properties listed as arguments to the properties watched for triggering invalidation.
  84. 		 * This method must be called during the startup lifecycle before buildRendering() completes,
  85. 		 * usually in preCreate().
  86. 		 */
  87. 		addInvalidatingProperties: function () {
  88. 			// summary:
  89. 			//		Adds the properties listed as arguments to the properties watched for triggering invalidation.
  90. 			// 		This method must be called during the startup lifecycle before buildRendering() completes,
  91. 			//		usually in preCreate().
  92. 			// description:
  93. 			//		This can be used to trigger invalidation for rendering or for both property and rendering. When
  94. 			//		no invalidation mechanism is specified, only the rendering refresh will be triggered, that is only
  95. 			//		the refreshRendering() method will be called.
  96. 			//		This method can either be called with a list of properties to invalidate the rendering as follows:
  97. 			//			this.addInvalidatingProperties("foo", "bar", ...);
  98. 			//		or with an hash of keys/values, the keys being the properties to invalidate and the values
  99. 			//		being the invalidation method (either rendering or property and rendering):
  100. 			//			this.addInvalidatingProperties({
  101. 			//				"foo": "invalidateProperty",
  102. 			//				"bar": "invalidateRendering"
  103. 			//			});
  104. 			// tags:
  105. 			//		protected
  106. 			if (this._invalidatingProperties == null) {
  107. 				this._invalidatingProperties = {};
  108. 			}
  109. 			for (var i = 0; i < arguments.length; i++) {
  110. 				if (typeof arguments[i] === "string") {
  111. 					// we just want the rendering to be refreshed
  112. 					this._invalidatingProperties[arguments[i]] = "invalidateRendering";
  113. 				} else {
  114. 					// we just merge key/value objects into our list of invalidating properties
  115. 					var props = Object.keys(arguments[i]);
  116. 					for (var j = 0; j < props.length; j++) {
  117. 						this._invalidatingProperties[props[j]] = arguments[i][props[j]];
  118. 					}
  119. 				}
  120. 			}
  121. 		},
  122. 		
  123. 		/**
  124. 		 * Invalidates the property for the next execution frame.
  125. 		 */
  126. 		invalidateProperty: function (name) {
  127. 			// summary:
  128. 			//		Invalidates the property for the next execution frame.
  129. 			// name: String?
  130. 			//		The name of the property to invalidate. If absent, the revalidation
  131. 			//		is performed without a particular property being invalidated, that is
  132. 			//		the argument passed to refreshProperties() does not contain is called without any argument.
  133. 			// tags:
  134. 			//		protected
  135. 			if (name) {
  136. 				this._invalidatedProperties[name] = true;
  137. 			}
  138. 			if (!this.invalidProperties) {
  139. 				this.invalidProperties = true;
  140. 				// if we have a pending render, let's cancel it to execute it post properties refresh
  141. 				if (this._renderHandle) {
  142. 					// TODO: if we switch to defer() use remove() here
  143. 					clearTimeout(this._renderHandle);
  144. 					this.invalidRendering = false;
  145. 					this._renderHandle = null;
  146. 				}
  147. 				// TODO: should be defer but we might change this mechanism to a centralized one, so keep it like
  148. 				// that for now. If we don't come up with a centralized one, move defer to Destroyable and require
  149. 				// the Destroyable mixin.
  150. 				setTimeout(lang.hitch(this, "validateProperties"), 0);
  151. 			}
  152. 		},
  153. 		
  154. 		/**
  155. 		 * Invalidates the rendering for the next execution frame.
  156. 		 */
  157. 		invalidateRendering: function (name) {
  158. 			// summary:
  159. 			//		Invalidates the rendering for the next execution frame.
  160. 			// name: String?
  161. 			//		The name of the property to invalidate. If absent then the revalidation is asked without a
  162. 			//		particular property being invalidated, that is refreshRendering() is called without
  163. 			//		any argument.
  164. 			// tags:
  165. 			//		protected
  166. 			if (name) {
  167. 				this._invalidatedProperties[name] = true;
  168. 			}
  169. 			if (!this.invalidRendering) {
  170. 				this.invalidRendering = true;
  171. 				// TODO: should be defer but we might change this mechanism to a centralized one, so keep it like
  172. 				// that for now. If we don't come up with a centralized one, move defer to Destroyable and require
  173. 				// the Destroyable mixin.
  174. 				this._renderHandle = setTimeout(lang.hitch(this, "validateRendering"), 0);
  175. 			}
  176. 		},
  177. 		
  178. 		validateProperties: function () {
  179. 			// summary:
  180. 			//		Immediately validates the properties.
  181. 			// description:
  182. 			//		Does nothing if no invalidating property is invalid.
  183. 			//		You generally do not call that method yourself.
  184. 			// tags:
  185. 			//		protected
  186. 			if (this.invalidProperties) {
  187. 				var props = lang.clone(this._invalidatedProperties);
  188. 				this.invalidProperties = false;
  189. 				this.refreshProperties(this._invalidatedProperties);
  190. 				this.emit("refresh-properties-complete",
  191. 					{ invalidatedProperties: props, bubbles: true, cancelable: false });
  192. 				// if there are properties still marked invalid pursue further with rendering refresh
  193. 				this.invalidateRendering();
  194. 			}
  195. 		},
  196. 		
  197. 		/**
  198. 		 * Immediately validates the rendering.
  199. 		 */
  200. 		validateRendering: function () {
  201. 			// summary:
  202. 			//		Immediately validates the rendering.
  203. 			// description:
  204. 			//		Does nothing if the rendering is not invalid.
  205. 			//		You generally do not call that method yourself.
  206. 			// tags:
  207. 			//		protected
  208. 			if (this.invalidRendering) {
  209. 				var props = lang.clone(this._invalidatedProperties);
  210. 				this.invalidRendering = false;
  211. 				this.refreshRendering(this._invalidatedProperties);
  212. 				// do not fully delete invalidateProperties because someone might have set a property in
  213. 				// its refreshRendering method (not wise but who knows what people are doing) and a new cycle
  214. 				// should start with that properties listed as invalid instead of a blank set of properties
  215. 				for (var key in props) {
  216. 					delete this._invalidatedProperties[key];
  217. 				}
  218. 				this.emit("refresh-rendering-complete",
  219. 					{ invalidatedProperties: props, bubbles: true, cancelable: false });
  220. 			}
  221. 		},
  222. 		
  223. 		/**
  224. 		 * Immediately validates the properties and the rendering.
  225. 		 */
  226. 		validate: function () {
  227. 			// summary:
  228. 			//		Immediately validates the properties and the rendering.
  229. 			// description:
  230. 			//		The method calls validateProperties() then validateRendering().
  231. 			//		You generally do not call that method yourself.
  232. 			// tags:
  233. 			//		protected
  234. 			this.validateProperties();
  235. 			this.validateRendering();
  236. 		},
  237. 		
  238. 		/**
  239. 		 * Actually refreshes the properties. 
  240. 		 */
  241. 		refreshProperties: function (/*jshint unused: vars */props) {
  242. 			// summary:
  243. 			//		Actually refreshes the properties. 
  244. 			// description:
  245. 			//		The default implementation does nothing. A class using this mixin
  246. 			//		should implement this method if it needs to react to changes
  247. 			//		of the value of an invalidating property, except for modifying the
  248. 			//		DOM in which case refreshRendering() should be used instead.
  249. 			//		Typically, this method should be overriden for implementing
  250. 			//		the reconciliation of properties, for instance for adjusting 
  251. 			//		interdependent properties such as "min", "max", and "value". 
  252. 			//		The mixin calls this method before refreshRendering().
  253. 			// props: Object
  254. 			//		A hash of invalidated properties. This hash will then be passed further down to the
  255. 			//		refreshRendering() method. As such any modification to this hash will be 
  256. 			//		visible in refreshRendering().
  257. 			// tags:
  258. 			//		protected
  259. 		},
  260. 		
  261. 		/**
  262. 		 * Actually refreshes the rendering.
  263. 		 */
  264. 		refreshRendering: function (/*jshint unused: vars */props) {
  265. 			// summary:
  266. 			//		Actually refreshes the rendering.
  267. 			// description:
  268. 			//		The default implementation does nothing. A class using this mixin
  269. 			//		should implement this method if it needs to modify the DOM in reaction 
  270. 			//		to changes of the value of invalidating properties.
  271. 			//		The mixin calls this method after refreshProperties().
  272. 			// props: Object
  273. 			//		A hash of invalidated properties.
  274. 			// tags:
  275. 			//		protected
  276. 		}
  277. 	});
  278. });