forked from jquery/api.jquery.com
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdeferred.then.xml
133 lines (126 loc) · 5.03 KB
/
deferred.then.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
<?xml version="1.0"?>
<entry name="deferred.then" type="method" return="Promise">
<title>deferred.then()</title>
<signature>
<added>1.8</added>
<argument name="doneFilter" type="Function">
<desc>
A 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>
<signature>
<added>1.5</added>
<removed>1.8</removed>
<argument name="doneCallbacks" type="Function">
<desc>
A function, or array of functions, called when the Deferred is resolved.
</desc>
</argument>
<argument name="failCallbacks" type="Function">
<desc>
A function, or array of functions, called when the Deferred is rejected.
</desc>
</argument>
</signature>
<signature>
<added>1.7</added>
<removed>1.8</removed>
<argument name="doneCallbacks" type="Function">
<desc>
A function, or array of functions, called when the Deferred is resolved.
</desc>
</argument>
<argument name="failCallbacks" type="Function">
<desc>
A function, or array of functions, called when the Deferred is rejected.
</desc>
</argument>
<argument name="progressCallbacks" type="Function" optional="true">
<desc>
A function, or array of functions, called when the Deferred notifies progress.
</desc>
</argument>
</signature>
<desc>Add handlers to be called when the Deferred object is resolved, rejected, or still in progress. </desc>
<longdesc>
<p><strong>Prior to jQuery 1.8</strong>, the arguments could be a function or an array of functions.</p>
<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>
<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>
<p>Callbacks are executed in the order they were added. Since
<code>deferred.then</code> returns a Promise, other methods of the
Promise object can be chained to this one, including additional
<code>.then()</code> methods.
</p>
</longdesc>
<example>
<desc>Since the <a href="/jQuery.get/"><code>jQuery.get</code></a> method returns a jqXHR object, which is derived from a Deferred object, we can attach handlers using the <code>.then</code> method.</desc>
<code><![CDATA[
$.get( "test.php" ).then(
function() {
alert( "$.get succeeded" );
}, function() {
alert( "$.get failed!" );
}
);
]]></code>
</example>
<example>
<desc>Filter the resolve value:</desc>
<html><![CDATA[
<button>Filter Resolve</button>
<p></p>
]]></html>
<code><![CDATA[
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 );
]]></code>
</example>
<example>
<desc>Filter reject value:</desc>
<code><![CDATA[
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 );
});
]]></code>
</example>
<example>
<desc>Chain tasks:</desc>
<code><![CDATA[
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
});
]]></code>
</example>
<category slug="deferred-object"/>
<category slug="version/1.5"/>
<category slug="version/1.7"/>
</entry>