Skip to content

Commit 352e17a

Browse files
kswedbergkswedberg
committed
Deprecate deferred.pipe() and update deferred.then()
Closes jquery#159
1 parent a9c32f7 commit 352e17a

2 files changed

Lines changed: 83 additions & 5 deletions

File tree

‎entries/deferred.pipe.xml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0"?>
2-
<entry name="deferred.pipe" type="method" return="Promise">
2+
<entry name="deferred.pipe" type="method" return="Promise" deprecated="1.8">
33
<title>deferred.pipe()</title>
44
<signature>
55
<added>1.6</added>
@@ -34,6 +34,7 @@
3434
</signature>
3535
<desc> Utility method to filter and/or chain Deferreds. </desc>
3636
<longdesc>
37+
<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>
3738
<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>
3839
</longdesc>
3940
<example>
@@ -81,4 +82,5 @@ chained.done(function( data ) {
8182
<category slug="deferred-object"/>
8283
<category slug="version/1.6"/>
8384
<category slug="version/1.7"/>
84-
</entry>
85+
<category slug="version/1.8"/>
86+
</entry>

‎entries/deferred.then.xml‎

Lines changed: 79 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,27 @@
11
<?xml version="1.0"?>
22
<entry name="deferred.then" type="method" return="Promise">
33
<title>deferred.then()</title>
4+
<signature>
5+
<added>1.8</added>
6+
<argument name="doneFilter" type="Function">
7+
<desc>
8+
A function that is called when the Deferred is resolved.
9+
</desc>
10+
</argument>
11+
<argument name="failFilter" type="Function" optional="true">
12+
<desc>
13+
An optional function that is called when the Deferred is rejected.
14+
</desc>
15+
</argument>
16+
<argument name="progressFilter" type="Function" optional="true">
17+
<desc>
18+
An optional function that is called when progress notifications are sent to the Deferred.
19+
</desc>
20+
</argument>
21+
</signature>
422
<signature>
523
<added>1.5</added>
24+
<removed>1.8</removed>
625
<argument name="doneCallbacks" type="Function">
726
<desc>
827
A function, or array of functions, called when the Deferred is resolved.
@@ -16,6 +35,7 @@
1635
</signature>
1736
<signature>
1837
<added>1.7</added>
38+
<removed>1.8</removed>
1939
<argument name="doneCallbacks" type="Function">
2040
<desc>
2141
A function, or array of functions, called when the Deferred is resolved.
@@ -32,10 +52,14 @@
3252
</desc>
3353
</argument>
3454
</signature>
35-
<desc> Add handlers to be called when the Deferred object is resolved or rejected. </desc>
55+
<desc>Add handlers to be called when the Deferred object is resolved, rejected, or still in progress. </desc>
56+
3657
<longdesc>
37-
<p>All three arguments (including progressCallbacks, as of jQuery 1.7) can be either a single function or an array of functions. The arguments can also be <code>null</code> if no callback of that type is desired. Alternatively, use <code>.done()</code>, <code>.fail()</code> or <code>.progress()</code> to set only one type of callback. </p>
38-
<p>When the Deferred is resolved, the doneCallbacks are called. If the Deferred is instead rejected, the failCallbacks are called. As of jQuery 1.7, the <code>deferred.notify()</code> or <code>deferred.notifyWith()</code> methods can be called to invoke the progressCallbacks as many times as desired before the Deferred is resolved or rejected.</p>
58+
<p><strong>Prior to jQuery 1.8</strong>, the arguments could be a function or an array of functions.</p>
59+
<p>For all signatures, the arguments can be <code>null</code> if no callback of that type is desired. Alternatively, use <code>.done()</code>, <code>.fail()</code> or <code>.progress()</code> to set only one type of callback without filtering status or values. </p>
60+
61+
<p><strong>As of jQuery 1.8</strong>, the <code>deferred.then()</code> method returns a new promise that can filter the status and values of a deferred through a function, replacing the now-deprecated <code>deferred.pipe()</code> method. The <code>doneFilter</code> and <code>failFilter</code> functions filter the original deferred's resolved / rejected status and values. The <code>progressFilter</code> function filters 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 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 promise's callbacks. If the filter function used is <code>null</code>, or not specified, the promise will be resolved or rejected with the same values as the original.</p>
62+
3963
<p>Callbacks are executed in the order they were added. Since
4064
<code>deferred.then</code> returns a Promise, other methods of the
4165
Promise object can be chained to this one, including additional
@@ -49,6 +73,58 @@ $.get("test.php").then(
4973
function(){ alert("$.get succeeded"); },
5074
function(){ alert("$.get failed!"); }
5175
);
76+
]]></code>
77+
</example>
78+
<example>
79+
<desc>Filter the resolve value:</desc>
80+
<html><![CDATA[
81+
<button>Filter Resolve</button>
82+
<p></p>
83+
]]></html>
84+
<code><![CDATA[
85+
var filterResolve = function() {
86+
87+
var defer = $.Deferred(),
88+
filtered = defer.then(function( value ) {
89+
return value * 2;
90+
});
91+
92+
defer.resolve( 5 );
93+
filtered.done(function( value ) {
94+
$( "p" ).html( "Value is ( 2*5 = ) 10: " + value );
95+
});
96+
};
97+
98+
$( "button" ).on( "click", filterResolve );
99+
]]></code>
100+
101+
</example>
102+
<example>
103+
<desc>Filter reject value:</desc>
104+
<code><![CDATA[
105+
var defer = $.Deferred(),
106+
filtered = defer.then( null, function( value ) {
107+
return value * 3;
108+
});
109+
110+
defer.reject( 6 );
111+
filtered.fail(function( value ) {
112+
alert( "Value is ( 3*6 = ) 18: " + value );
113+
});
114+
]]></code>
115+
</example>
116+
<example>
117+
<desc>Chain tasks:</desc>
118+
<code><![CDATA[
119+
var request = $.ajax( url, { dataType: "json" } ),
120+
chained = request.then(function( data ) {
121+
return $.ajax( url2, { data: { user: data.userId } } );
122+
});
123+
124+
chained.done(function( data ) {
125+
// data retrieved from url2 as provided by the first request
126+
});
127+
52128
]]></code>
53129
</example>
54130
<category slug="deferred-object"/>

0 commit comments

Comments
 (0)