deferred.pipe()    **DEPRECATED 1.8** JQ Home  <<  Objects  <<  deferred.pipe()

Deferred filtering and/or chaining.

Description

The deferred.pipe() Deferred utility method for filtering and/or chaining a Deferred object.

  • If the arguments passed to the deferred.pipe() method are null or not specified, the piped deferred will be progressed, resolved or rejected with the same values as the original Deferred object.
  • The filter functions used by the deferred.pipe() method can return either:
    • A new value to be passed along to the piped deferred deferred.progress(), deferred.done() or deferred.fail() callbacks. This effectively allows us to pipe future deferreds based on the outcome of current deferred. Therefore we don't have to wait for one asynchronous function to end before deciding what to do after it has ended.
    • Another observable object which will pass its resolved, rejected or notified status and values to the piped deferred's callbacks. If a non-deferred value or no value is returned from the piped deferred, then this will be immediately resolved, rejected or notified with the value dependant upon the outcome of the original Deferred object.

This method was deprecated in jQuery 1.8 and is replaced by the deferred.then() method that was revamped for this purpose in jQuery 1.8.

Syntax

Signature Description
deferred.pipe( [doneCallback] [, failCallback]
             [, progressCallback] )
Utility method for filtering and/or chaining a Deferred object.

Parameters

Parameter Description Type
doneCallback Optional function that is called when the Deferred is resolved.Function
failCallback Optional function that is called when the Deferred is rejected.Function
progressCallback Optional function that is called when progress notifications are sent to the Deferred.Function

Return

A Promise object which is just a copy of a Deferred object without any notify/resolve/reject methods.


deferred.pipe( [doneCallback] [, failCallback]
                         [, progressCallback] )
ExamplesObjects  <<  Top

Utility method for filtering and/or chaining a Deferred object.

In the example below when we press the left button the first time we create a Deferred object. We then use a piped defer that will react to doneCallbacks from the original Deferred. We then resolve the original referred which calls back the piped defer passing a message. We add to the message passed to the piped deferred and output it below.

When we press the centre button the first time we create a Deferred object. We then use a piped defer that will react to failCallbacks from the original Deferred. We then reject the original referred which calls back the piped defer passing a message. We add to the message passed to the piped deferred and output it below.

When we press the right button the first time we create a Deferred object. We then use a piped defer that will react to doneCallbacks and progressCallbacks from the original Deferred. We then notify and resolve the original referred which calls back the piped defer passing a message each time. We add to the messages passed to the piped deferred and output it below.


$(function(){
  $('#btn23').one('click', function(){
    var ourDeferred = $.Deferred();
    pipedDefer = ourDeferred.pipe( function ( value ) {
      return value + ' Returning from "pipedDefer", so will be resolved. <br>';
    });
    ourDeferred.resolve( 'Resolving "ourDeferred". <br>' );
    pipedDefer.done(function( value ) {
      aFunc( value, '#div1' );
    });
  });
  $('#btn24').one('click', function(){
    var ourDeferred = $.Deferred();
    pipedDefer = ourDeferred.pipe( null, function ( value ) {
      return value + ' Returning from "pipedDefer", so will be rejected. <br><br>';
    });
    ourDeferred.reject( 'Rejecting "ourDeferred". <br>' );
    pipedDefer.fail(function( value ) {
   	  aFunc( value, '#div1' );
   	});
  });
  $('#btn25').one('click', function(){
    var ourDeferred = $.Deferred();
    pipedDefer = ourDeferred.pipe( 
      function ( value ) {
        return value + ' Returning from "pipedDefer", so will be resolved. <br><br>';
      },
      null, 
      function ( value ) {
        return value + ' Returning from "pipedDefer", so will be notified. <br>';
      }
    );
    ourDeferred.notify( 'Notifying "ourDeferred". <br>' );
    ourDeferred.resolve( 'Resolving "ourDeferred". <br>' );
    pipedDefer.progress( function( value ) {
      aFunc( value, '#div1' );
    });
    pipedDefer.done( function( value ) {
      aFunc( value, '#div1' );
    });
  });
});

div1. Some initial text.

Press the button below to action the above code:

                         

Related Tutorials

jQuery Advanced Tutorials - Lesson 7 - The Deferred Object