| Read more about this book |
(For more resources on this subject, see here.)
The jQuery object itself also contains several properties that can be useful when working with animations. These include:
- jQuery.fx.off
- jQuery.fx.interval
The queue is not restricted to storing animation methods; other methods can also be added to the queue. We will only be looking at the queue() method from an animation perspective here.
Working with the queue
When several effects are chained together, the first effect is begun straight away. The remaining effects are stored as functions in an array in the element’s fx queue. As the effects are stored in an array, we can call standard JavaScript array methods on it to manipulate it, and examine its properties to find out additional information about it.
We can determine how many functions are in the queue by looking at the length property of the array, or we can call standard functions such as push(), pop(), or reverse() on it to perform various operations on the items (functions) in the array. It is unlikely that this would be required in most normal situations however.
An important point to note about the queue is that the first effect method called on an element does not get stored in the queue, so the length of the queue at the start of the operation will always be one less than the total number of effect methods called on the element.
The queue executes on a first-in-first-out basis, with the last function stored in the queue executing last. The default fx queue for an animated element will run automatically and each function contained within it will be called automatically by jQuery. The string inprogress is used as the first item in the default fx queue as a flag indicating that the queue is currently being run.
A custom queue that we create ourselves will not run automatically and we must ensure that each item in the queue is executed one after the other. jQuery provides several ways of doing this including the dequeue() method, which executes the next function in the queue, and a callback function that we can pass into functions in the queue. We’ll look at both of these techniques later in the article.
Viewing the queue
To view the queue we simply call the queue() method; no arguments are required but we can optionally supply the queue name if it differs from the default fx. When the method is called, it returns an array containing the remaining functions in the queue. The queue() method may be used in the following form:
jQuery(elements).queue([queue name], [new queue], [callback]);
In addition to the name of the queue, we can also supply either a new queue, or a single callback function. The new queue, if supplied, should take the form of an array of functions. The new queue will replace the existing queue entirely. Passing an empty array to the queue() method will clear the queue. A callback passed to the queue() method will be added to the end of the queue and executed last after the functions originally in the queue.
A common use of the queue() method is to look at the length property of the returned array to determine how many functions are left to run; but if we need to, we can also look at each function individually by calling the toString() JavaScript function on any item in the array (except for item 0 which will simply display the string inprogress).
Most functions in the returned array are function literals, however, the “next” item in the queue is not available via the queue() method. The contents of item 0 in the default fx queue will always be the string inprogress as this is the animation currently being run.
Time for action – viewing the queue
Let’s look at a basic example of the use of the queue() method and the type of results we can expect to obtain.
- In the <head> of our template file add the following code:
<style>
#fader { width:100px; height:100px; background-color:#000; }
</style> - Finally, in the anonymous function at the bottom of the second <script> element, add the following code:
$(“#fader”).fadeOut(function() {
console.log($(this).queue());
}).fadeIn().fadeOut().fadeIn();
- Save the page as queue.html.
What just happened?
Typically, we’d use an external stylesheet for any styling, but for a single selector and three rules, it seems pointless creating a separate file. In the script we have four effects chained together to form a simple animation in which our <div> element is simply faded out and back in twice. We provide a callback function as an argument to the first of our effect methods, within which we call the queue() method.
You’ll need to use a browser that has a console for this example, such as Firefox. Here’s what the output looks like in Firebug:
In the previous screenshot, we can see that the array making up the queue has been output to the console for us to view. There are three items left in the queue when the method is called. The first item in the array is the string inprogress. The remaining two items are the queued methods that have not yet run.
If we wish to see how many functions are left in the queue (including the one that is in progress), we could change the console.log line to this:
console.log($(this).queue().length);
This code would show the following output in Firebug’s console:
This time our console shows numerically how many items are left in the queue, as shown in the previous screenshot.
We can use other array methods on the queue if we wish (although this would rarely be useful), such as push() or pop() to add or remove items for example. We can also get a single item from the queue if we wish, by adding square braces and an index number after the call to queue():
console.log($(this).queue()[1]);
As shown above, this time the value of the second item is output to the console. As I mentioned earlier, we can see the actual contents of the function using the toString() JavaScript function:
console.log($(this).queue()[1].toString);
Running this code produces the following output:
(Move the mouse over the image to enlarge it.)
The code shown in the previous screenshot won’t make much sense to the casual observer as it’s been minified, but it’s the contents of jQuery’s fadeout() method.
Adding a function to the queue
Appending a new function to the end of the queue is a trivial matter and we don’t even need to use a new method. We just need to pass the new function, or a function reference, to the queue() method as an argument.
When we pass a single function into the queue() method and we are working with the default fx queue, jQuery will automatically call the function for us using the dequeue() method. We haven’t looked at the dequeue() method yet, but we will cover this a little later in the article.
