deferred.then( doneFilter [, failFilter ] [, progressFilter ] )Returns: Promise
Description: Add handlers to be called when the Deferred object is resolved, rejected, or still in progress.
-
version added: 1.8deferred.then( doneFilter [, failFilter ] [, progressFilter ] )
- doneFilterType: Function()A function that is called when the Deferred is resolved.
- failFilterType: Function()An optional function that is called when the Deferred is rejected.
- progressFilterType: Function()An optional function that is called when progress notifications are sent to the Deferred.
-
-
version added: 1.5, removed: 1.8deferred.then( doneCallbacks, failCallbacks )
-
version added: 1.7, removed: 1.8deferred.then( doneCallbacks, failCallbacks [, progressCallbacks ] )
- doneCallbacksType: Function()A function, or array of functions, called when the Deferred is resolved.
- failCallbacksType: Function()A function, or array of functions, called when the Deferred is rejected.
- progressCallbacksType: Function()A function, or array of functions, called when the Deferred notifies progress.
-
Prior to jQuery 1.8, the arguments could be a function or an array of functions.
For all signatures, the arguments can be null
if no callback of that type is desired. Alternatively, use .done()
, .fail()
or .progress()
to set only one type of callback without filtering status or values.
As of jQuery 1.8, the deferred.then()
method returns a new promise that can filter the status and values of a deferred through a function, replacing the now-deprecated deferred.pipe()
method. The doneFilter
and failFilter
functions filter the original deferred's resolved / rejected status and values. The progressFilter
function filters any calls to the original deferred's notify
or notifyWith
methods. These filter functions can return a new value to be passed along to the promise's .done()
or .fail()
callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the promise's callbacks. If the filter function used is null
, or not specified, the promise will be resolved or rejected with the same values as the original.
Callbacks are executed in the order they were added. Since deferred.then
returns a Promise, other methods of the Promise object can be chained to this one, including additional .then()
methods.
Examples:
Since the jQuery.get
method returns a jqXHR object, which is derived from a Deferred object, we can attach handlers using the .then
method.
$.get( "test.php" ).then( function() { alert( "$.get succeeded" ); }, function() { alert( "$.get failed!" ); } );
Filter the resolve value:
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>deferred.then demo</title> <script src="https://code.jquery.com/jquery-1.10.2.js" rel="external nofollow" ></script> </head> <body> <button>Filter Resolve</button> <p></p> <script> var filterResolve = function() { var defer = $.Deferred(), filtered = defer.then(function( value ) { return value * 2; }); defer.resolve( 5 ); filtered.done(function( value ) { $( "p" ).html( "Value is ( 2*5 = ) 10: " + value ); }); }; $( "button" ).on( "click", filterResolve ); </script> </body> </html>
Demo:
Filter reject value:
var defer = $.Deferred(), filtered = defer.then( null, function( value ) { return value * 3; }); defer.reject( 6 ); filtered.fail(function( value ) { alert( "Value is ( 3*6 = ) 18: " + value ); });
Chain tasks:
var request = $.ajax( url, { dataType: "json" } ), chained = request.then(function( data ) { return $.ajax( url2, { data: { user: data.userId } } ); }); chained.done(function( data ) { // data retrieved from url2 as provided by the first request });