Delaying queued functions

Another queue-oriented activity you might want to perform is to add a delay between the executions of queued functions. The delay() method enables that.

Method syntax: delay
delay(duration[, queueName])
Adds a delay to all unexecuted functions in the named queue.
Parameters
duration	(Number|String) The delay duration in milliseconds, or one of the strings “fast”, “normal”, or “slow”, representing values of 200, 400, and 600 respectively.
queueName	(String) The name of the queue from which the functions are to be delayed. If omitted, the default effects queue of fx is assumed
Returns
The jQuery collection.

To see where delay() comes in handy, imagine that you have an image, having my-image as its ID, that you want to hide and then show again after one second. You can do this with the following statement:

$('#my-image')
        .slideUp('slow')
        .delay(1000)
        .slideDown('fast');

This method is useful but not so flexible because it isn’t possible to cancel a delay once it’s set.

Before moving to the next lesson, there’s one more thing to discuss regarding queuing functions.

Inserting functions into the effects queue

We mentioned that internally jQuery uses a queue named fx to queue up the functions necessary to implement the animations. What if you’d like to add your own functions to this queue in order to intersperse actions within a queued series of effects? Now that you know about the queuing methods, you can!

Think back to the previous example in listing 8.7, where you used four animations to make the moon revolve around the Earth. Imagine that you wanted to turn the background of the moon image black after the second animation (the one that moves it downward). If you just added a call to the css() method between the second and third animations (in bold) as follows

var $moonImage = $('img[alt="moon"]');
$moonImage.animate({left: '+=256'}, 2500);
$moonImage.animate({top: '+=256'}, 2500);
$moonImage.css({backgroundColor: 'black'});
$moonImage.animate({left: '-=256'}, 2500);
$moonImage.animate({top: '-=256'}, 2500);

you’d be disappointed because this would cause the background to change immediately, perhaps even before the first animation had a chance to start (remember that animate() is a non-blocking method). Rather, consider the following code (the change is in bold):

var $moonImage = $('img[alt="moon"]');
$moonImage.animate({left: '+=256'}, 2500);
$moonImage.animate({top: '+=256'}, 2500);
$moonImage.queue('fx',
  function() {
    $(this)
         .css({backgroundColor: 'black'});
         .dequeue('fx');
  }
);
$moonImage.animate({left: '-=256'}, 2500);
$moonImage.animate({top: '-=256'}, 2500);

Here you wrap the call to the css() method in a function that you place onto the fx queue using the queue() method. (We could have omitted the queue name, because fx is the default, but we made it explicit here for clarity.) This puts your color-changing function into place on the effects queue where it will be called as part of the function chain that executes as the animations progress, between the second and third animations.

But note! After you call the css() method, you call the dequeue() method on the fx queue. This is absolutely necessary to keep the animation queue chugging along. Failure to call dequeue() at this point will cause the animations to grind to a halt, because nothing is causing the next function in the chain to execute. The unexecuted animations will just sit there on the effects queues until either something causes a dequeue and the functions commence or the page unloads and everything gets discarded.

In addition to this change, ponder this: what color will the background be after the animation is completed? Because you don’t perform other changes, it will remain black. This is something you want to avoid, and so you should restore both the position and the background of the moon. The last parameter of animate(), the callback function, is what you need. You can restore the original background color (white) of the image inside this callback, as shown here:

If you’d like to see this process in action, load the page in the file lesson-8/-revolutions.2.html into your browser and click the Animate button.

Queuing functions comes in handy whenever you want to execute functions consecutively but without the overhead, or complexity, of nesting functions in asynchronous callbacks. Today there are more advanced techniques and methods to tackle this issue (usually referred to as “callback hell”), which we’ll discuss in lesson 13 when talking about the Deferred and Promise objects. But that’s another lesson.