Skip to content

Commit b27aac1

Browse files
kswedbergkswedberg
committed
Upate jqXHR method names and add deprecation note.
Closes jquery#223
1 parent b1da4b4 commit b27aac1

File tree

2 files changed

+62
-63
lines changed

2 files changed

+62
-63
lines changed

‎entries/jQuery.get.xml

Lines changed: 27 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
});
2828
</code></pre>
2929
<p>The <code>success</code> callback function is passed the returned data, which will be an XML root element, text string, JavaScript file, or JSON object, depending on the MIME type of the response. It is also passed the text status of the response. </p>
30-
<p><strong>As of jQuery 1.5</strong>, the <code>success</code> callback function is also passed a <a href="http://api.jquery.com/jQuery.get/#jqxhr-object">"jqXHR" object</a> (in <strong>jQuery 1.4</strong>, it was passed the <code>XMLHttpRequest</code> object). However, since JSONP and cross-domain GET requests do not use <abbr title="XMLHTTPRequest">XHR</abbr>, in those cases the <code>(j)XHR</code> and <code>textStatus</code> parameters passed to the success callback are undefined.</p>
30+
<p><strong>As of jQuery 1.5</strong>, the <code>success</code> callback function is also passed a <a href="/#jqxhr-object">"jqXHR" object</a> (in <strong>jQuery 1.4</strong>, it was passed the <code>XMLHttpRequest</code> object). However, since JSONP and cross-domain GET requests do not use <abbr title="XMLHTTPRequest">XHR</abbr>, in those cases the <code>jqXHR</code> and <code>textStatus</code> parameters passed to the success callback are undefined.</p>
3131
<p>Most implementations will specify a success handler:</p>
3232
<pre><code>$.get('ajax/test.html', function(data) {
3333
$('.result').html(data);
@@ -36,21 +36,24 @@
3636
</code></pre>
3737
<p>This example fetches the requested HTML snippet and inserts it on the page.</p>
3838
<h4 id="jqxhr-object">The jqXHR Object</h4>
39-
<p><strong>As of jQuery 1.5</strong>, all of jQuery's Ajax methods return a superset of the <code>XMLHTTPRequest</code> object. This jQuery XHR object, or "jqXHR," returned by <code>$.get()</code> implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see <a href="http://api.jquery.com/category/deferred-object/">Deferred object</a> for more information). For convenience and consistency with the callback names used by <code><a href="http://api.jquery.com/jQuery.ajax/">$.ajax()</a></code>, it provides <code>.error()</code>, <code>.success()</code>, and <code>.complete()</code> methods. These methods take a function argument that is called when the request terminates, and the function receives the same arguments as the correspondingly-named <code>$.ajax()</code> callback.</p>
40-
<p>The Promise interface in jQuery 1.5 also allows jQuery's Ajax methods, including <code>$.get()</code>, to chain multiple <code>.success()</code>, <code>.complete()</code>, and <code>.error()</code> callbacks on a single request, and even to assign these callbacks after the request may have completed. If the request is already complete, the callback is fired immediately.</p>
39+
<p><strong>As of jQuery 1.5</strong>, all of jQuery's Ajax methods return a superset of the <code>XMLHTTPRequest</code> object. This jQuery XHR object, or "jqXHR," returned by <code>$.get()</code> implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see <a href="/category/deferred-object/">Deferred object</a> for more information). The <code>jqXHR.done()</code> (for success), <code>jqXHR.fail() (for error)</code>, and <code>jqXHR.always()</code> (for completion, whether success or error) methods take a function argument that is called when the request terminates. For information about the arguments this function receives, see the <a href="/jQuery.ajax/#jqXHR">jqXHR Object</a> section of the $.ajax() documentation.</p>
40+
<p>The Promise interface also allows jQuery's Ajax methods, including <code>$.get()</code>, to chain multiple <code>.done()</code>, <code>.fail()</code>, and <code>.always()</code> callbacks on a single request, and even to assign these callbacks after the request may have completed. If the request is already complete, the callback is fired immediately.</p>
4141
<pre><code>// Assign handlers immediately after making the request,
42-
// and remember the jqxhr object for this request
43-
var jqxhr = $.get("example.php", function() {
44-
alert("success");
45-
})
46-
.success(function() { alert("second success"); })
47-
.error(function() { alert("error"); })
48-
.complete(function() { alert("complete"); });
42+
// and remember the jqxhr object for this request
43+
var jqxhr = $.get("example.php", function() {
44+
alert("success");
45+
})
46+
.done(function() { alert("second success"); })
47+
.fail(function() { alert("error"); })
48+
.always(function() { alert("finished"); });
4949

50-
// perform other work here ...
50+
// perform other work here ...
5151

52-
// Set another completion function for the request above
53-
jqxhr.complete(function(){ alert("second complete"); });</code></pre>
52+
// Set another completion function for the request above
53+
jqxhr.always(function(){ alert("second finished"); });
54+
</code></pre>
55+
<h4>Deprecation Notice</h4>
56+
<p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods introduced in jQuery 1.5 are <strong>deprecated as of jQuery 1.8</strong>. To prepare your code for their eventual removal, use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
5457
</longdesc>
5558
<note id="same-origin-policy" type="additional"/>
5659
<note id="use-ajaxerror" type="additional" data-title="jQuery.get()"/>
@@ -64,26 +67,26 @@
6467
<code><![CDATA[$.get("test.php", { name: "John", time: "2pm" } );]]></code>
6568
</example>
6669
<example>
67-
<desc>pass arrays of data to the server (while still ignoring the return results).</desc>
70+
<desc>Pass arrays of data to the server (while still ignoring the return results).</desc>
6871
<code><![CDATA[$.get("test.php", { 'choices[]': ["Jon", "Susan"]} );]]></code>
6972
</example>
7073
<example>
71-
<desc>Alert out the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
72-
<code><![CDATA[$.get("test.php", function(data){
73-
alert("Data Loaded: " + data);
74+
<desc>Alert the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
75+
<code><![CDATA[$.get("test.php", function(data) {
76+
alert("Data Loaded: " + data);
7477
});]]></code>
7578
</example>
7679
<example>
77-
<desc>Alert out the results from requesting test.cgi with an additional payload of data (HTML or XML, depending on what was returned).</desc>
78-
<code><![CDATA[$.get("test.cgi", { name: "John", time: "2pm" },
79-
function(data){
80-
alert("Data Loaded: " + data);
81-
});]]></code>
80+
<desc>Alert the results from requesting test.cgi with an additional payload of data (HTML or XML, depending on what was returned).</desc>
81+
<code><![CDATA[$.get("test.cgi", { name: "John", time: "2pm" })
82+
.done(function(data) {
83+
alert("Data Loaded: " + data);
84+
});]]></code>
8285
</example>
8386
<example>
84-
<desc> Gets the test.php page contents, which has been returned in json format (&lt;?php echo json_encode(array("name"=&gt;"John","time"=&gt;"2pm")); ?&gt;), and adds it to the page.</desc>
87+
<desc> Get the test.php page contents, which has been returned in json format (&lt;?php echo json_encode(array("name"=&gt;"John","time"=&gt;"2pm")); ?&gt;), and add it to the page.</desc>
8588
<code><![CDATA[$.get("test.php",
86-
function(data){
89+
function(data) {
8790
$('body').append( "Name: " + data.name ) // John
8891
.append( "Time: " + data.time ); // 2pm
8992
}, "json");]]></code>

‎entries/jQuery.post.xml

Lines changed: 35 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
});
2929
</code></pre>
3030
<p>The <code>success</code> callback function is passed the returned data, which will be an XML root element or a text string depending on the MIME type of the response. It is also passed the text status of the response.</p>
31-
<p><strong>As of jQuery 1.5</strong>, the <code>success</code> callback function is also passed a <a href="http://api.jquery.com/jQuery.get/#jqxhr-object">"jqXHR" object</a> (in <strong>jQuery 1.4</strong>, it was passed the <code>XMLHttpRequest</code> object).</p>
31+
<p><strong>As of jQuery 1.5</strong>, the <code>success</code> callback function is also passed a <a href="#jqxhr-object">"jqXHR" object</a> (in <strong>jQuery 1.4</strong>, it was passed the <code>XMLHttpRequest</code> object).</p>
3232
<p>Most implementations will specify a success handler:</p>
3333
<pre><code>$.post('ajax/test.html', function(data) {
3434
$('.result').html(data);
@@ -37,22 +37,25 @@
3737
<p>This example fetches the requested HTML snippet and inserts it on the page.</p>
3838
<p>Pages fetched with <code>POST</code> are never cached, so the <code>cache</code> and <code>ifModified</code> options in <code><a href="/jQuery.ajaxSetup">jQuery.ajaxSetup()</a></code> have no effect on these requests.</p>
3939
<h4 id="jqxhr-object">The jqXHR Object</h4>
40-
<p><strong>As of jQuery 1.5</strong>, all of jQuery's Ajax methods return a superset of the <code>XMLHTTPRequest</code> object. This jQuery XHR object, or "jqXHR," returned by <code>$.post()</code> implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see <a href="http://api.jquery.com/category/deferred-object/">Deferred object</a> for more information). For convenience and consistency with the callback names used by <code><a href="http://api.jquery.com/jQuery.ajax/">$.ajax()</a></code>, it provides <code>.error()</code>, <code>.success()</code>, and <code>.complete()</code> methods. These methods take a function argument that is called when the request terminates, and the function receives the same arguments as the correspondingly-named <code>$.ajax()</code> callback.</p>
41-
<p>The Promise interface in jQuery 1.5 also allows jQuery's Ajax methods, including <code>$.post()</code>, to chain multiple <code>.success()</code>, <code>.complete()</code>, and <code>.error()</code> callbacks on a single request, and even to assign these callbacks after the request may have completed. If the request is already complete, the callback is fired immediately.</p>
40+
<p><strong>As of jQuery 1.5</strong>, all of jQuery's Ajax methods return a superset of the <code>XMLHTTPRequest</code> object. This jQuery XHR object, or "jqXHR," returned by <code>$.get()</code> implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see <a href="/category/deferred-object/">Deferred object</a> for more information). The <code>jqXHR.done()</code> (for success), <code>jqXHR.fail() (for error)</code>, and <code>jqXHR.always()</code> (for completion, whether success or error) methods take a function argument that is called when the request terminates. For information about the arguments this function receives, see the <a href="/jQuery.ajax/#jqXHR">jqXHR Object</a> section of the $.ajax() documentation.</p>
41+
<p>The Promise interface also allows jQuery's Ajax methods, including <code>$.get()</code>, to chain multiple <code>.done()</code>, <code>.fail()</code>, and <code>.always()</code> callbacks on a single request, and even to assign these callbacks after the request may have completed. If the request is already complete, the callback is fired immediately.</p>
4242
<pre><code>// Assign handlers immediately after making the request,
43-
// and remember the jqxhr object for this request
44-
var jqxhr = $.post("example.php", function() {
45-
alert("success");
46-
})
47-
.success(function() { alert("second success"); })
48-
.error(function() { alert("error"); })
49-
.complete(function() { alert("complete"); });
43+
// and remember the jqxhr object for this request
44+
var jqxhr = $.post("example.php", function() {
45+
alert("success");
46+
})
47+
.done(function() { alert("second success"); })
48+
.fail(function() { alert("error"); })
49+
.always(function() { alert("finished"); });
5050

51-
// perform other work here ...
51+
// perform other work here ...
5252

53-
// Set another completion function for the request above
54-
jqxhr.complete(function(){ alert("second complete"); });
55-
</code></pre>
53+
// Set another completion function for the request above
54+
jqxhr.always(function(){ alert("second finished"); });
55+
</code></pre>
56+
57+
<h4>Deprecation Notice</h4>
58+
<p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods introduced in jQuery 1.5 are <strong>deprecated as of jQuery 1.8</strong>. To prepare your code for their eventual removal, use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
5659
</longdesc>
5760
<note id="same-origin-policy" type="additional"/>
5861
<note id="use-ajaxerror" type="additional" data-title="jQuery.post()"/>
@@ -65,37 +68,29 @@
6568
<code><![CDATA[$.post("test.php", { name: "John", time: "2pm" } );]]></code>
6669
</example>
6770
<example>
68-
<desc>pass arrays of data to the server (while still ignoring the return results).</desc>
71+
<desc>Pass arrays of data to the server (while still ignoring the return results).</desc>
6972
<code><![CDATA[$.post("test.php", { 'choices[]': ["Jon", "Susan"] });]]></code>
7073
</example>
7174
<example>
72-
<desc>send form data using ajax requests</desc>
75+
<desc>Send form data using ajax requests</desc>
7376
<code><![CDATA[$.post("test.php", $("#testform").serialize());]]></code>
7477
</example>
7578
<example>
76-
<desc>Alert out the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
79+
<desc>Alert the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
7780
<code><![CDATA[$.post("test.php", function(data) {
7881
alert("Data Loaded: " + data);
7982
});]]></code>
8083
</example>
8184
<example>
82-
<desc>Alert out the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).</desc>
83-
<code><![CDATA[$.post("test.php", { name: "John", time: "2pm" },
84-
function(data) {
85-
alert("Data Loaded: " + data);
86-
});]]></code>
87-
</example>
88-
<example>
89-
<desc>Gets the test.php page content, store it in a XMLHttpResponse object and applies the process() JavaScript function.</desc>
90-
<code><![CDATA[$.post("test.php", { name: "John", time: "2pm" },
91-
function(data) {
92-
process(data);
93-
},
94-
"xml"
95-
);]]></code>
85+
<desc>Alert the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).</desc>
86+
<code><![CDATA[$.post("test.php", { name: "John", time: "2pm" })
87+
.done(function(data) {
88+
alert("Data Loaded: " + data);
89+
});
90+
]]></code>
9691
</example>
9792
<example>
98-
<desc>Posts to the test.php page and gets contents which has been returned in json format (&lt;?php echo json_encode(array("name"=&gt;"John","time"=&gt;"2pm")); ?&gt;).</desc>
93+
<desc>Post to the test.php page and get content which has been returned in json format (&lt;?php echo json_encode(array("name"=&gt;"John","time"=&gt;"2pm")); ?&gt;).</desc>
9994
<code><![CDATA[$.post("test.php", { "func": "getNameAndTime" },
10095
function(data){
10196
console.log(data.name); // John
@@ -116,13 +111,14 @@ $("#searchForm").submit(function(event) {
116111
term = $form.find( 'input[name="s"]' ).val(),
117112
url = $form.attr( 'action' );
118113
119-
/* Send the data using post and put the results in a div */
120-
$.post( url, { s: term },
121-
function( data ) {
122-
var content = $( data ).find( '#content' );
123-
$( "#result" ).empty().append( content );
124-
}
125-
);
114+
/* Send the data using post */
115+
var posting = $.post( url, { s: term } );
116+
117+
/* Put the results in a div */
118+
posting.done(function( data ) {
119+
var content = $( data ).find( '#content' );
120+
$( "#result" ).empty().append( content );
121+
});
126122
});
127123
]]></code>
128124
<html><![CDATA[<form action="/" id="searchForm">

0 commit comments

Comments
 (0)