deferred.pipe.xml

<?xml version="1.0"?>
<entry name="deferred.pipe" type="method" return="Promise" deprecated="1.8">
  <title>deferred.pipe()</title>
  <signature>
    <added>1.6</added>
    <argument name="doneFilter" type="Function" optional="true">
      <desc>
        An optional function that is called when the Deferred is resolved.
      </desc>
    </argument>
    <argument name="failFilter" type="Function" optional="true">
      <desc>
        An optional function that is called when the Deferred is rejected.
      </desc>
    </argument>
  </signature>
  <signature>
    <added>1.7</added>
    <argument name="doneFilter" type="Function" optional="true">
      <desc>
        An optional function that is called when the Deferred is resolved.
      </desc>
    </argument>
    <argument name="failFilter" type="Function" optional="true">
      <desc>
        An optional function that is called when the Deferred is rejected.
      </desc>
    </argument>
    <argument name="progressFilter" type="Function" optional="true">
      <desc>
        An optional function that is called when progress notifications are sent to the Deferred.
      </desc>
    </argument>
  </signature>
  <desc> Utility method to filter and/or chain Deferreds.  </desc>
  <longdesc>
    <div class="warning">
      <p><strong>Deprecation Notice:</strong>As of jQuery 1.8, the deferred.pipe() method is deprecated. The <code>deferred.then()</code> method, which replaces it, should be used instead.</p>
    </div>
    <p>The <code>deferred.pipe()</code> method returns a new promise that filters the status and values of a deferred through a function.  The <code>doneFilter</code> and <code>failFilter</code> functions filter the original deferred's resolved / rejected status and values. <strong>As of jQuery 1.7</strong>, the method also accepts a <code>progressFilter</code> function to filter any calls to the original deferred's <code>notify</code> or <code>notifyWith</code> methods. These filter functions can return a new value to be passed along to the piped promise's <code>done()</code> or <code>fail()</code> 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 <code>null</code>, or not specified, the piped promise will be resolved or rejected with the same values as the original.</p>
  </longdesc>
  <example>
    <desc>Filter resolve value:</desc>
    <code><![CDATA[
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 );
});
]]></code>
  </example>
  <example>
    <desc>Filter reject value:</desc>
    <code><![CDATA[
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 );
});
]]></code>
  </example>
  <example>
    <desc>Chain tasks:</desc>
    <code><![CDATA[
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
});
]]></code>
  </example>
  <category slug="deferred-object"/>
  <category slug="version/1.6"/>
  <category slug="version/1.7"/>
  <category slug="version/1.8"/>
  <category slug="deprecated/deprecated-1.8"/>
</entry>