jQuery Can Provide Queue-Based Promise Objects
Last week, I was looking up some Promise information in the jQuery API when I came across the .promise() fn-method. While I have worked with promises in the context of AJAX and explicit Deferred objects, it seems that jQuery provides implicit promise functionality around their queues and dequeuing functionality. This allows for promise objects to be returned for animations, which are, after all, nothing more than encapsulated "fx" queues.
By default, the animation methods in jQuery (animate(), slideDown(), slideUp(), etc.) return a reference to the jQuery object (in order to maintain method chaining). And traditionally, if you want to perform an action after an animation is complete, you have to provide some sort of callback as an argument or property of the animation configuration.
With the .promise() method, however, you can get a promise object that will be resolved once the animation is done. This provides for more readable code (in my opinion) with the option for multiple callback handlers. To see what I'm talking about, take a look at the following code. In this demo, we're going to hide and show a DIV and alter the "action text" once the animation has been completed.
<!DOCTYPE html>
<html>
<head>
<title>jQuery Can Provide Queue-Based Promise Objects</title>
<style type="text/css">
div.container > div.buffer {
background-color: #E0E0E0 ;
border: 1px solid #CCCCCC ;
height: 200px ;
padding: 10px 10px 10px 10px ;
}
</style>
</head>
<body>
<h1>
jQuery Can Provide Queue-Based Promise Objects
</h1>
<p>
<a href="#" class="action">
<span class="intent">Hide</span> Div
</a>
</p>
<div class="container">
<div class="buffer">
Hello, I am a div! How you like me now?
</div>
</div>
<!-- Include scripts. -->
<script type="text/javascript" src="./jquery-1.6.4.js"></script>
<script type="text/javascript">
// Get a reference to some DOM elements.
var action = $( "a.action" );
var actionIntent = action.find( "span.intent" );
var container = $( "div.container" );
// Hook up the click action.
action.click(
function( event ){
// Prevent the real event - not a true link.
event.preventDefault();
// Check to make sure we're not currently animating
// the DIV.
if (container.is( ":animated" )){
// Let the animation continue before the action
// link becomes a viable action.
return;
}
// Toggle the container. When implementing this
// animation, get a PROMISE object for the animating
// DOM element so that we can attach completion
// handlers to it.
var promise = container.slideToggle().promise();
// When the animation is done, update the text within
// the action link.
promise.done(
function(){
// Set the text of the action intent.
if (container.is( ":visible" )){
actionIntent.text( "Hide" );
} else {
actionIntent.text( "Show" );
}
}
);
}
);
</script>
</body>
</html>
As you can see, we are using the .slideToggle() method for animation. However, after we call the slideToggle() method, we are chaining it with the promise() method:
var promise = container.slideToggle().promise();
This returns a promise object rather than the jQuery object. Once we have the promise object, we can start to attach completion handlers using the done() method. This allows us to invoke zero or more callbacks once the animation has completed.
The documentation for the .promise() method doesn't mention anything about fail() outcomes. In my testing, I found that calling stop() on an animation did not trigger a fail() callback handler. However, if I called stop() and included the jump-to-end parameter, the done() callbacks would be invoked. So, it looks as if the only viable callback collection will be that of a successful completion.
Using .promise() with jQuery animation is not revolutionary. It doesn't provide any completely new functionality. What it does provide is a way to define callbacks in an easier, more readable, more flexible way. Also, when you consider the $.when() method, queue-based promise objects make it much easier to coordinate multiple animations.
Want to use code from this post? Check out the license.
Reader Comments
This is cool because other methods to deal with the timing would involve timeouts, but due to congestion in the single-threaded JS execution order events could trigger out of synch and this removes that problem. Cool!
@Randy,
I think the animation queue still works with timeouts under the hood; but the nice thing about this is that it will work with custom made queues as well.
I'm going to try to use this method with executeSql commands.
"After you're done dropping the table, create the table".
"After you're done creating the table, insert into the table".
http://stackoverflow.com/questions/8748473/jquery-promise-deferred