Skip to content
Browse files

Upate jqXHR method names and add deprecation note.

Closes #223
  • Loading branch information...
1 parent b1da4b4 commit b27aac1422e13de5dac9e5113741b9918705856b @kswedberg kswedberg committed
Showing with 62 additions and 63 deletions.
  1. +27 −24 entries/jQuery.get.xml
  2. +35 −39 entries/jQuery.post.xml
View
51 entries/jQuery.get.xml
@@ -27,7 +27,7 @@
});
</code></pre>
<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>
- <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>
+ <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>
<p>Most implementations will specify a success handler:</p>
<pre><code>$.get('ajax/test.html', function(data) {
$('.result').html(data);
@@ -36,21 +36,24 @@
</code></pre>
<p>This example fetches the requested HTML snippet and inserts it on the page.</p>
<h4 id="jqxhr-object">The jqXHR Object</h4>
- <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>
- <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>
+ <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>
+ <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>
<pre><code>// Assign handlers immediately after making the request,
- // and remember the jqxhr object for this request
- var jqxhr = $.get("example.php", function() {
- alert("success");
- })
- .success(function() { alert("second success"); })
- .error(function() { alert("error"); })
- .complete(function() { alert("complete"); });
+// and remember the jqxhr object for this request
+var jqxhr = $.get("example.php", function() {
+ alert("success");
+})
+.done(function() { alert("second success"); })
+.fail(function() { alert("error"); })
+.always(function() { alert("finished"); });
- // perform other work here ...
+// perform other work here ...
- // Set another completion function for the request above
- jqxhr.complete(function(){ alert("second complete"); });</code></pre>
+// Set another completion function for the request above
+jqxhr.always(function(){ alert("second finished"); });
+</code></pre>
+ <h4>Deprecation Notice</h4>
+ <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>
</longdesc>
<note id="same-origin-policy" type="additional"/>
<note id="use-ajaxerror" type="additional" data-title="jQuery.get()"/>
@@ -64,26 +67,26 @@
<code><![CDATA[$.get("test.php", { name: "John", time: "2pm" } );]]></code>
</example>
<example>
- <desc>pass arrays of data to the server (while still ignoring the return results).</desc>
+ <desc>Pass arrays of data to the server (while still ignoring the return results).</desc>
<code><![CDATA[$.get("test.php", { 'choices[]': ["Jon", "Susan"]} );]]></code>
</example>
<example>
- <desc>Alert out the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
- <code><![CDATA[$.get("test.php", function(data){
-alert("Data Loaded: " + data);
+ <desc>Alert the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
+ <code><![CDATA[$.get("test.php", function(data) {
+ alert("Data Loaded: " + data);
});]]></code>
</example>
<example>
- <desc>Alert out the results from requesting test.cgi with an additional payload of data (HTML or XML, depending on what was returned).</desc>
- <code><![CDATA[$.get("test.cgi", { name: "John", time: "2pm" },
- function(data){
- alert("Data Loaded: " + data);
- });]]></code>
+ <desc>Alert the results from requesting test.cgi with an additional payload of data (HTML or XML, depending on what was returned).</desc>
+ <code><![CDATA[$.get("test.cgi", { name: "John", time: "2pm" })
+.done(function(data) {
+ alert("Data Loaded: " + data);
+});]]></code>
</example>
<example>
- <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>
+ <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>
<code><![CDATA[$.get("test.php",
- function(data){
+ function(data) {
$('body').append( "Name: " + data.name ) // John
.append( "Time: " + data.time ); // 2pm
}, "json");]]></code>
View
74 entries/jQuery.post.xml
@@ -28,7 +28,7 @@
});
</code></pre>
<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>
- <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>
+ <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>
<p>Most implementations will specify a success handler:</p>
<pre><code>$.post('ajax/test.html', function(data) {
$('.result').html(data);
@@ -37,22 +37,25 @@
<p>This example fetches the requested HTML snippet and inserts it on the page.</p>
<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>
<h4 id="jqxhr-object">The jqXHR Object</h4>
- <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>
- <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>
+ <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>
+ <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>
<pre><code>// Assign handlers immediately after making the request,
- // and remember the jqxhr object for this request
- var jqxhr = $.post("example.php", function() {
- alert("success");
- })
- .success(function() { alert("second success"); })
- .error(function() { alert("error"); })
- .complete(function() { alert("complete"); });
+// and remember the jqxhr object for this request
+var jqxhr = $.post("example.php", function() {
+ alert("success");
+})
+.done(function() { alert("second success"); })
+.fail(function() { alert("error"); })
+.always(function() { alert("finished"); });
- // perform other work here ...
+// perform other work here ...
- // Set another completion function for the request above
- jqxhr.complete(function(){ alert("second complete"); });
- </code></pre>
+// Set another completion function for the request above
+jqxhr.always(function(){ alert("second finished"); });
+</code></pre>
+
+ <h4>Deprecation Notice</h4>
+ <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>
</longdesc>
<note id="same-origin-policy" type="additional"/>
<note id="use-ajaxerror" type="additional" data-title="jQuery.post()"/>
@@ -65,37 +68,29 @@
<code><![CDATA[$.post("test.php", { name: "John", time: "2pm" } );]]></code>
</example>
<example>
- <desc>pass arrays of data to the server (while still ignoring the return results).</desc>
+ <desc>Pass arrays of data to the server (while still ignoring the return results).</desc>
<code><![CDATA[$.post("test.php", { 'choices[]': ["Jon", "Susan"] });]]></code>
</example>
<example>
- <desc>send form data using ajax requests</desc>
+ <desc>Send form data using ajax requests</desc>
<code><![CDATA[$.post("test.php", $("#testform").serialize());]]></code>
</example>
<example>
- <desc>Alert out the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
+ <desc>Alert the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
<code><![CDATA[$.post("test.php", function(data) {
alert("Data Loaded: " + data);
});]]></code>
</example>
<example>
- <desc>Alert out the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).</desc>
- <code><![CDATA[$.post("test.php", { name: "John", time: "2pm" },
- function(data) {
- alert("Data Loaded: " + data);
- });]]></code>
- </example>
- <example>
- <desc>Gets the test.php page content, store it in a XMLHttpResponse object and applies the process() JavaScript function.</desc>
- <code><![CDATA[$.post("test.php", { name: "John", time: "2pm" },
- function(data) {
- process(data);
- },
- "xml"
-);]]></code>
+ <desc>Alert the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).</desc>
+ <code><![CDATA[$.post("test.php", { name: "John", time: "2pm" })
+.done(function(data) {
+ alert("Data Loaded: " + data);
+});
+]]></code>
</example>
<example>
- <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>
+ <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>
<code><![CDATA[$.post("test.php", { "func": "getNameAndTime" },
function(data){
console.log(data.name); // John
@@ -116,13 +111,14 @@ $("#searchForm").submit(function(event) {
term = $form.find( 'input[name="s"]' ).val(),
url = $form.attr( 'action' );
- /* Send the data using post and put the results in a div */
- $.post( url, { s: term },
- function( data ) {
- var content = $( data ).find( '#content' );
- $( "#result" ).empty().append( content );
- }
- );
+ /* Send the data using post */
+ var posting = $.post( url, { s: term } );
+
+ /* Put the results in a div */
+ posting.done(function( data ) {
+ var content = $( data ).find( '#content' );
+ $( "#result" ).empty().append( content );
+ });
});
]]></code>
<html><![CDATA[<form action="/" id="searchForm">

0 comments on commit b27aac1

Please sign in to comment.
Something went wrong with that request. Please try again.