Version: 1.0, Last updated: 1/5/2010
| jQuery Message Queuing: Get all your JavaScript ducks in a row | Version: 1.0, Last updated: 1/5/2010 |
| License | Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses. |
| Examples | These working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used. |
| Support and Testing | Information about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself). |
| Release History | |
| Functions | |
| jQuery.jqmq | Create a new queue. |
| queueObj.add | Add a single item onto the queue. |
| queueObj. | Add multiple items onto the queue, individually. |
| queueObj. | Start a currently paused queue. |
| queueObj.next | Intended to be called from within the jQuery.jqmq callback, this method will continue a queue with a delay of -1. |
| queueObj. | Clear a queue completely. |
| queueObj. | Pause a currently running queue. |
| queueObj. | Update an existing queue’s options. |
| queueObj.size | Get the current queue length. |
| queueObj. | Get the current index in the queue of the passed item. |
| jQuery. | Add a jQuery collection of elements onto the queue. |
| jQuery. | Add each selected element from a jQuery collection onto the queue, individually. |
Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses. http://benalman.com/about/license/
These working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.
| Serial AJAX | http://benalman.com |
| Throttling | http://benalman.com |
Information about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).
| jQuery Versions | 1.3.2, 1.4a2 |
| Browsers Tested | Internet Explorer 6-8, Firefox 2-3.7, Safari 3-4, Chrome, Opera 9.6-10. |
| Unit Tests | http://benalman.com |
Create a new queue.
var queueObj = jQuery.jqmq( options );
| options | (Object) An object containing options specific to this queue. |
| delay | (Number) Time in milliseconds between each callback execution. If delay is -1, queue will wait for a queueObj.next call instead of auto-executing. Defaults to 100. |
| batch | (Number) Number of queue items to process at a time. If less than this number of items remain in the queue, the remainder will be processed. Defaults to 1. |
| queue | (Array) Populate the queue initially with these items. Defaults to an empty initial queue. |
| callback | (Function) Called for each queue item or batch of items, every delay milliseconds. This function is passed a single argument, which is the single queue item if batch is 1, or an array of queue items if batch is > 1. If callback returns true, the queue item(s) will be re- added back onto the front of the queue for the next callback execution to retry. Inside this function, `this` refers to the queueObj object. |
| complete | (Function) Called whenever there are no longer any queue items to process. After completion, if more queue items are added and the queue completes again, this function will be called again. Inside this function, `this` refers to the queueObj object. |
| paused | (Boolean) If true, initialize this queue in a paused state. Defaults to false. |
(Object) a reference to the jqmq queue object.
Add a single item onto the queue. If you want to add multiple items onto the queue individually, use queueObj.addEach. If the queue was empty and not paused, processing will resume immediately.
queueObj.add( item [, priority ] );
| item | (Anything) A single item to add to the queue. |
| priority | (Boolean) If true, the item is added to the front of the queue, otherwise the item is added to the end of the queue. Defaults to false. |
(Number) The length of the queue, after the item has been added.
Add multiple items onto the queue, individually. If you want to add a single item onto the queue, use queueObj.add. If the queue was empty and not paused, processing will resume immediately.
queueObj.addEach( items [, priority ] );
| items | (Array) An array of items to add to the queue. |
| priority | (Boolean) If true, the items are added to the front of the queue, otherwise the items are added to the end of the queue. Defaults to false. |
(Number) The length of the queue, after the items have been added.
Intended to be called from within the jQuery.jqmq callback, this method will continue a queue with a delay of -1. This is most useful for queues of asynchronous-but-serial actions, like AJAX requests that must execute in order, but not overlap.
queueObj.next( [ retry ] );
| retry | (Boolean) If true, the queue item(s) will be re-added back to the front of the queue to be retried on the next queue execution. |
Nothing.
Pause a currently running queue. A paused but empty queue will need to be manually restarted with queueObj.start even after new items are added.
queueObj.pause();
Nothing.
Update an existing queue’s options.
queueObj.update( options );
| options | (Object) An object containing options specific to this queue. |
The delay, batch, callback and complete options from jQuery.jqmq can be updated. The queue and paused state can be changed using the other queueObj methods.
Nothing.
Add a jQuery collection of elements onto the queue. If you want to add each selected element onto the queue individually, use jQuery.fn.jqmqAddEach. If the queue was empty and not paused, processing will resume immediately.
jQuery('selector').jqmqAdd( queueObj [, priority ] );| queueObj | (Object) A valid jqmq object, returned from jQuery.jqmq. |
| priority | (Boolean) If true, the item is added to the front of the queue, otherwise the item is added to the end of the queue. Defaults to false. |
(jQuery) The initial jQuery collection of elements.
Add each selected element from a jQuery collection onto the queue, individually. If you want to add the entire jQuery collection of elements onto the queue as a single item, use jQuery.fn.jqmqAdd. If the queue was empty and not paused, processing will resume immediately.
jQuery('selector').jqmqAddEach( queueObj [, priority ] );| queueObj | (Object) A valid jqmq object, returned from jQuery.jqmq. |
| priority | (Boolean) If true, the items are added to the front of the queue, otherwise the items are added to the end of the queue. Defaults to false. |
(jQuery) The initial jQuery collection of elements.