jquery.dotimeout.js 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285
  1. /*!
  2. * jQuery doTimeout: Like setTimeout, but better! - v1.0 - 3/3/2010
  3. * http://benalman.com/projects/jquery-dotimeout-plugin/
  4. *
  5. * Copyright (c) 2010 "Cowboy" Ben Alman
  6. * Dual licensed under the MIT and GPL licenses.
  7. * http://benalman.com/about/license/
  8. */
  9. // Script: jQuery doTimeout: Like setTimeout, but better!
  10. //
  11. // *Version: 1.0, Last updated: 3/3/2010*
  12. //
  13. // Project Home - http://benalman.com/projects/jquery-dotimeout-plugin/
  14. // GitHub - http://github.com/cowboy/jquery-dotimeout/
  15. // Source - http://github.com/cowboy/jquery-dotimeout/raw/master/jquery.ba-dotimeout.js
  16. // (Minified) - http://github.com/cowboy/jquery-dotimeout/raw/master/jquery.ba-dotimeout.min.js (1.0kb)
  17. //
  18. // About: License
  19. //
  20. // Copyright (c) 2010 "Cowboy" Ben Alman,
  21. // Dual licensed under the MIT and GPL licenses.
  22. // http://benalman.com/about/license/
  23. //
  24. // About: Examples
  25. //
  26. // These working examples, complete with fully commented code, illustrate a few
  27. // ways in which this plugin can be used.
  28. //
  29. // Debouncing - http://benalman.com/code/projects/jquery-dotimeout/examples/debouncing/
  30. // Delays, Polling - http://benalman.com/code/projects/jquery-dotimeout/examples/delay-poll/
  31. // Hover Intent - http://benalman.com/code/projects/jquery-dotimeout/examples/hoverintent/
  32. //
  33. // About: Support and Testing
  34. //
  35. // Information about what version or versions of jQuery this plugin has been
  36. // tested with, what browsers it has been tested in, and where the unit tests
  37. // reside (so you can test it yourself).
  38. //
  39. // jQuery Versions - 1.3.2, 1.4.2
  40. // Browsers Tested - Internet Explorer 6-8, Firefox 2-3.6, Safari 3-4, Chrome 4-5, Opera 9.6-10.1.
  41. // Unit Tests - http://benalman.com/code/projects/jquery-dotimeout/unit/
  42. //
  43. // About: Release History
  44. //
  45. // 1.0 - (3/3/2010) Callback can now be a string, in which case it will call
  46. // the appropriate $.method or $.fn.method, depending on where .doTimeout
  47. // was called. Callback must now return `true` (not just a truthy value)
  48. // to poll.
  49. // 0.4 - (7/15/2009) Made the "id" argument optional, some other minor tweaks
  50. // 0.3 - (6/25/2009) Initial release
  51. (function($){
  52. '$:nomunge'; // Used by YUI compressor.
  53. var cache = {},
  54. // Reused internal string.
  55. doTimeout = 'doTimeout',
  56. // A convenient shortcut.
  57. aps = Array.prototype.slice;
  58. // Method: jQuery.doTimeout
  59. //
  60. // Initialize, cancel, or force execution of a callback after a delay.
  61. //
  62. // If delay and callback are specified, a doTimeout is initialized. The
  63. // callback will execute, asynchronously, after the delay. If an id is
  64. // specified, this doTimeout will override and cancel any existing doTimeout
  65. // with the same id. Any additional arguments will be passed into callback
  66. // when it is executed.
  67. //
  68. // If the callback returns true, the doTimeout loop will execute again, after
  69. // the delay, creating a polling loop until the callback returns a non-true
  70. // value.
  71. //
  72. // Note that if an id is not passed as the first argument, this doTimeout will
  73. // NOT be able to be manually canceled or forced. (for debouncing, be sure to
  74. // specify an id).
  75. //
  76. // If id is specified, but delay and callback are not, the doTimeout will be
  77. // canceled without executing the callback. If force_mode is specified, the
  78. // callback will be executed, synchronously, but will only be allowed to
  79. // continue a polling loop if force_mode is true (provided the callback
  80. // returns true, of course). If force_mode is false, no polling loop will
  81. // continue, even if the callback returns true.
  82. //
  83. // Usage:
  84. //
  85. // > jQuery.doTimeout( [ id, ] delay, callback [, arg ... ] );
  86. // > jQuery.doTimeout( id [, force_mode ] );
  87. //
  88. // Arguments:
  89. //
  90. // id - (String) An optional unique identifier for this doTimeout. If id is
  91. // not specified, the doTimeout will NOT be able to be manually canceled or
  92. // forced.
  93. // delay - (Number) A zero-or-greater delay in milliseconds after which
  94. // callback will be executed.
  95. // callback - (Function) A function to be executed after delay milliseconds.
  96. // callback - (String) A jQuery method to be executed after delay
  97. // milliseconds. This method will only poll if it explicitly returns
  98. // true.
  99. // force_mode - (Boolean) If true, execute that id's doTimeout callback
  100. // immediately and synchronously, continuing any callback return-true
  101. // polling loop. If false, execute the callback immediately and
  102. // synchronously but do NOT continue a callback return-true polling loop.
  103. // If omitted, cancel that id's doTimeout.
  104. //
  105. // Returns:
  106. //
  107. // If force_mode is true, false or undefined and there is a
  108. // yet-to-be-executed callback to cancel, true is returned, but if no
  109. // callback remains to be executed, undefined is returned.
  110. $[doTimeout] = function() {
  111. return p_doTimeout.apply( window, [ 0 ].concat( aps.call( arguments ) ) );
  112. };
  113. // Method: jQuery.fn.doTimeout
  114. //
  115. // Initialize, cancel, or force execution of a callback after a delay.
  116. // Operates like <jQuery.doTimeout>, but the passed callback executes in the
  117. // context of the jQuery collection of elements, and the id is stored as data
  118. // on the first element in that collection.
  119. //
  120. // If delay and callback are specified, a doTimeout is initialized. The
  121. // callback will execute, asynchronously, after the delay. If an id is
  122. // specified, this doTimeout will override and cancel any existing doTimeout
  123. // with the same id. Any additional arguments will be passed into callback
  124. // when it is executed.
  125. //
  126. // If the callback returns true, the doTimeout loop will execute again, after
  127. // the delay, creating a polling loop until the callback returns a non-true
  128. // value.
  129. //
  130. // Note that if an id is not passed as the first argument, this doTimeout will
  131. // NOT be able to be manually canceled or forced (for debouncing, be sure to
  132. // specify an id).
  133. //
  134. // If id is specified, but delay and callback are not, the doTimeout will be
  135. // canceled without executing the callback. If force_mode is specified, the
  136. // callback will be executed, synchronously, but will only be allowed to
  137. // continue a polling loop if force_mode is true (provided the callback
  138. // returns true, of course). If force_mode is false, no polling loop will
  139. // continue, even if the callback returns true.
  140. //
  141. // Usage:
  142. //
  143. // > jQuery('selector').doTimeout( [ id, ] delay, callback [, arg ... ] );
  144. // > jQuery('selector').doTimeout( id [, force_mode ] );
  145. //
  146. // Arguments:
  147. //
  148. // id - (String) An optional unique identifier for this doTimeout, stored as
  149. // jQuery data on the element. If id is not specified, the doTimeout will
  150. // NOT be able to be manually canceled or forced.
  151. // delay - (Number) A zero-or-greater delay in milliseconds after which
  152. // callback will be executed.
  153. // callback - (Function) A function to be executed after delay milliseconds.
  154. // callback - (String) A jQuery.fn method to be executed after delay
  155. // milliseconds. This method will only poll if it explicitly returns
  156. // true (most jQuery.fn methods return a jQuery object, and not `true`,
  157. // which allows them to be chained and prevents polling).
  158. // force_mode - (Boolean) If true, execute that id's doTimeout callback
  159. // immediately and synchronously, continuing any callback return-true
  160. // polling loop. If false, execute the callback immediately and
  161. // synchronously but do NOT continue a callback return-true polling loop.
  162. // If omitted, cancel that id's doTimeout.
  163. //
  164. // Returns:
  165. //
  166. // When creating a <jQuery.fn.doTimeout>, the initial jQuery collection of
  167. // elements is returned. Otherwise, if force_mode is true, false or undefined
  168. // and there is a yet-to-be-executed callback to cancel, true is returned,
  169. // but if no callback remains to be executed, undefined is returned.
  170. $.fn[doTimeout] = function() {
  171. var args = aps.call( arguments ),
  172. result = p_doTimeout.apply( this, [ doTimeout + args[0] ].concat( args ) );
  173. return typeof args[0] === 'number' || typeof args[1] === 'number'
  174. ? this
  175. : result;
  176. };
  177. function p_doTimeout( jquery_data_key ) {
  178. var that = this,
  179. elem,
  180. data = {},
  181. // Allows the plugin to call a string callback method.
  182. method_base = jquery_data_key ? $.fn : $,
  183. // Any additional arguments will be passed to the callback.
  184. args = arguments,
  185. slice_args = 4,
  186. id = args[1],
  187. delay = args[2],
  188. callback = args[3];
  189. if ( typeof id !== 'string' ) {
  190. slice_args--;
  191. id = jquery_data_key = 0;
  192. delay = args[1];
  193. callback = args[2];
  194. }
  195. // If id is passed, store a data reference either as .data on the first
  196. // element in a jQuery collection, or in the internal cache.
  197. if ( jquery_data_key ) { // Note: key is 'doTimeout' + id
  198. // Get id-object from the first element's data, otherwise initialize it to {}.
  199. elem = that.eq(0);
  200. elem.data( jquery_data_key, data = elem.data( jquery_data_key ) || {} );
  201. } else if ( id ) {
  202. // Get id-object from the cache, otherwise initialize it to {}.
  203. data = cache[ id ] || ( cache[ id ] = {} );
  204. }
  205. // Clear any existing timeout for this id.
  206. data.id && clearTimeout( data.id );
  207. delete data.id;
  208. // Clean up when necessary.
  209. function cleanup() {
  210. if ( jquery_data_key ) {
  211. elem.removeData( jquery_data_key );
  212. } else if ( id ) {
  213. delete cache[ id ];
  214. }
  215. };
  216. // Yes, there actually is a setTimeout call in here!
  217. function actually_setTimeout() {
  218. data.id = setTimeout( function(){ data.fn(); }, delay );
  219. };
  220. if ( callback ) {
  221. // A callback (and delay) were specified. Store the callback reference for
  222. // possible later use, and then setTimeout.
  223. data.fn = function( no_polling_loop ) {
  224. // If the callback value is a string, it is assumed to be the name of a
  225. // method on $ or $.fn depending on where doTimeout was executed.
  226. if ( typeof callback === 'string' ) {
  227. callback = method_base[ callback ];
  228. }
  229. callback.apply( that, aps.call( args, slice_args ) ) === true && !no_polling_loop
  230. // Since the callback returned true, and we're not specifically
  231. // canceling a polling loop, do it again!
  232. ? actually_setTimeout()
  233. // Otherwise, clean up and quit.
  234. : cleanup();
  235. };
  236. // Set that timeout!
  237. actually_setTimeout();
  238. } else if ( data.fn ) {
  239. // No callback passed. If force_mode (delay) is true, execute the data.fn
  240. // callback immediately, continuing any callback return-true polling loop.
  241. // If force_mode is false, execute the data.fn callback immediately but do
  242. // NOT continue a callback return-true polling loop. If force_mode is
  243. // undefined, simply clean up. Since data.fn was still defined, whatever
  244. // was supposed to happen hadn't yet, so return true.
  245. delay === undefined ? cleanup() : data.fn( delay === false );
  246. return true;
  247. } else {
  248. // Since no callback was passed, and data.fn isn't defined, it looks like
  249. // whatever was supposed to happen already did. Clean up and quit!
  250. cleanup();
  251. }
  252. };
  253. })(jQuery);