deferred.pipe()
deferred.pipe( [doneFilter] [, failFilter] ) Returns: Promise
Description: Utility method to filter and/or chain Deferreds.
-
version added: 1.6deferred.pipe( [doneFilter] [, failFilter] )
doneFilter An optional function that is called when the Deferred is resolved.
failFilter An optional function that is called when the Deferred is rejected.
-
version added: 1.7deferred.pipe( [doneFilter] [, failFilter] [, progressFilter] )
doneFilter An optional function that is called when the Deferred is resolved.
failFilter An optional function that is called when the Deferred is rejected.
progressFilter An optional function that is called when the Deferred is rejected.
The deferred.pipe() method returns a new promise that filters the status and values of a deferred through a function. The doneFilter and failFilter functions filter the original deferred's resolved / rejected status and values. As of jQuery 1.7, the method also accepts a progressFilter function to filter 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 piped 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 piped promise's callbacks. If the filter function used is null, or not specified, the piped promise will be resolved or rejected with the same values as the original.
Examples:
Example: Filter resolve value:
var defer = $.Deferred(),
filtered = defer.pipe(function( value ) {
return value * 2;
});
defer.resolve( 5 );
filtered.done(function( value ) {
alert( "Value is ( 2*5 = ) 10: " + value );
});
Example: Filter reject value:
var defer = $.Deferred(),
filtered = defer.pipe( null, function( value ) {
return value * 3;
});
defer.reject( 6 );
filtered.fail(function( value ) {
alert( "Value is ( 3*6 = ) 18: " + value );
});
Example: Chain tasks:
var request = $.ajax( url, { dataType: "json" } ),
chained = request.pipe(function( data ) {
return $.ajax( url2, { data: { user: data.userId } } );
});
chained.done(function( data ) {
// data retrieved from url2 as provided by the first request
});