Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Add jQuery.Deferred() entry (replacing some deferred object desc)

  • Loading branch information...
commit 6b565fa3fa7d41be092e334acf41b78683214692 1 parent 20172f6
@kswedberg kswedberg authored
Showing with 39 additions and 20 deletions.
  1. +3 −16 categories.xml
  2. +32 −0 entries/jQuery.Deferred.xml
  3. +4 −4 pages/Types.html
View
19 categories.xml
@@ -31,21 +31,8 @@
<desc><![CDATA[These methods allow us to associate arbitrary data with specific DOM elements.]]></desc>
</category>
<category name="Deferred Object" slug="deferred-object">
- <desc><![CDATA[
- <p><code>jQuery.Deferred()</code>, introduced in version 1.5, is a chainable utility object that can register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.</p>
- <div class="longdesc">
- <p>In JavaScript it is common to invoke functions that optionally accept callbacks that are called within that function.</p>
- <p>For example, in versions prior to jQuery 1.5, asynchronous processes such as <code>jQuery.ajax()</code> accept callbacks to be invoked some time in the near-future upon success, error, and completion of the ajax request.</p>
- <p><code>jQuery.Deferred()</code> introduces several enhancements to the way callbacks are managed and invoked. In particular, <code>jQuery.Deferred()</code> provides flexible ways to provide multiple callbacks, and these callbacks can be invoked regardless of whether the original callback dispatch has already occurred. jQuery Deferred is based on the <a href="http://wiki.commonjs.org/wiki/Promises/A">CommonJS Promises/A</a> design.</p>
- <p>One model for understanding Deferred is to think of it as a chain-aware function wrapper. The <a href="http://api.jquery.com/deferred.then"><code>deferred.then()</code></a>, <a href="http://api.jquery.com/deferred.done"><code>deferred.done()</code></a>, and <a href="http://api.jquery.com/deferred.fail"><code>deferred.fail()</code></a> methods specify the functions to be called and the <a href="http://api.jquery.com/deferred.resolve"><code>deferred.resolve(args)</code></a> or <a href="http://api.jquery.com/deferred.reject"><code>deferred.reject(args)</code></a> methods "call" the functions with the arguments you supply. Once the Deferred has been resolved or rejected it stays in that state; a second call to <code>deferred.resolve()</code> is ignored for example. If more functions are added by <code>deferred.then()</code> after the Deferred is resolved, they are called immediately with the arguments previously provided.</p>
- <p>In most cases where a jQuery API call returns a Deferred or Deferred-compatible object, such as <a href="http://api.jquery.com/jQuery.ajax"><code>jQuery.ajax()</code></a> or <a href="http://api.jquery.com/jQuery.when"><code>jQuery.when()</code></a>, you will only want to use the <a href="http://api.jquery.com/deferred.then"><code>deferred.then()</code></a>, <a href="http://api.jquery.com/deferred.done"><code>deferred.done()</code></a>, and <a href="http://api.jquery.com/deferred.fail"><code>deferred.fail()</code></a> methods to add callbacks to the Deferred's queues. The internals of the API call or code that created the Deferred will invoke <a href="http://api.jquery.com/deferred.resolve"><code>deferred.resolve()</code></a> or <a href="http://api.jquery.com/deferred.reject"><code>deferred.reject()</code></a> on the deferred at some point, causing the appropriate callbacks to run.</p>
- <h4>jQuery.Deferred Constructor</h4>
- <p>The <code>jQuery.Deferred()</code> constructor creates a new Deferred object. The <code>new</code> operator is optional.</p>
- <p><code>jQuery.Deferred</code> can be passed an optional function, which is called just before the constructor returns and is passed the constructed <code>deferred</code> object as both the <code>this</code> object and as the first argument to the function. The called function can attach callbacks using <a href="http://api.jquery.com/deferred.then"><code>deferred.then()</code></a> for example.</p>
- <p>A Deferred object starts in the <em>pending</em> state. Any callbacks added to the object with <a href="http://api.jquery.com/deferred.then"><code>deferred.then()</code></a>, <a href="http://api.jquery.com/deferred.done"><code>deferred.done()</code></a>, or <a href="http://api.jquery.com/deferred.fail"><code>deferred.fail()</code></a> are queued to be executed later. Calling <a href="http://api.jquery.com/deferred.resolve"><code>deferred.resolve()</code></a> or <a href="http://api.jquery.com/deferred.resolveWith"><code>deferred.resolveWith()</code></a> transitions the Deferred into the <em>resolved</em> state and immediately executes any <code>doneCallbacks</code> that are set. Calling <a href="http://api.jquery.com/deferred.reject"><code>deferred.reject()</code></a> or <a href="http://api.jquery.com/deferred.rejectWith"><code>deferred.rejectWith()</code></a> transitions the Deferred into the <em>rejected</em> state and immediately executes any <code>failCallbacks</code> that are set. Once the object has entered the resolved or rejected state, it stays in that state. Callbacks can still be added to the resolved or rejected Deferred -- they will execute immediately.</p>
- <p>The Deferred object is chainable, similar to the way a jQuery object is chainable, but it has its own methods. After creating a Deferred object, you can use any of the methods below by either chaining directly from the object creation or saving the object in a variable and invoking one or more methods on that variable.</p>
- </div>
- ]]></desc>
+ <desc><![CDATA[<p>The Deferred object, introduced in jQuery 1.5, is a chainable utility object created by calling the <a href="/jQuery.Deferred/"><code>jQuery.Deferred()</code></a> method. It can register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.</p>
+ <p>The Deferred object is chainable, similar to the way a jQuery object is chainable, but it has its own methods. After creating a Deferred object, you can use any of the methods below by either chaining directly from the object creation or saving the object in a variable and invoking one or more methods on that variable.</p>]]></desc>
</category>
<category name="Deprecated" slug="deprecated">
<desc><![CDATA[These items have been deprecated, though not necessarily removed, from jQuery.]]></desc>
@@ -383,4 +370,4 @@
</category>
<category name="All" slug="all"/>
</category>
-</categories>
+</categories>
View
32 entries/jQuery.Deferred.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<entry name="jQuery.Deferred" type="method" return="Deferred">
+ <title>jQuery.Deferred()</title>
+ <signature>
+ <added>1.5</added>
+ <argument name="beforeStart" type="Function" optional="true">
+ <desc>
+ A function that is called just before the constructor returns.
+ </desc>
+ <argument name="deferred" type="Deferred">
+ <desc>
+ The constructed Deferred object.
+ </desc>
+ </argument>
+ </argument>
+ </signature>
+ <desc> A constructor function that returns a chainable utility object with methods to register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.</desc>
+ <longdesc>
+ <p>The <code>jQuery.Deferred()</code> constructor creates a new Deferred object. The <code>new</code> operator is optional.</p>
+ <p>The <code>jQuery.Deferred</code> method can be passed an optional function, which is called just before the constructor returns and is passed the constructed <code>deferred</code> object as both the <code>this</code> object and as the first argument to the function. The called function can attach callbacks using <a href="/deferred.then"><code>deferred.then()</code></a>, for example.</p>
+ <p>A Deferred object starts in the <em>pending</em> state. Any callbacks added to the object with <a href="/deferred.then"><code>deferred.then()</code></a>, <a href="/deferred.always"><code>deferred.always()</code></a>, <a href="/deferred.done"><code>deferred.done()</code></a>, or <a href="/deferred.fail"><code>deferred.fail()</code></a> are queued to be executed later. Calling <a href="/deferred.resolve"><code>deferred.resolve()</code></a> or <a href="/deferred.resolveWith"><code>deferred.resolveWith()</code></a> transitions the Deferred into the <em>resolved</em> state and immediately executes any <code>doneCallbacks</code> that are set. Calling <a href="/deferred.reject"><code>deferred.reject()</code></a> or <a href="/deferred.rejectWith"><code>deferred.rejectWith()</code></a> transitions the Deferred into the <em>rejected</em> state and immediately executes any <code>failCallbacks</code> that are set. Once the object has entered the resolved or rejected state, it stays in that state. Callbacks can still be added to the resolved or rejected Deferred — they will execute immediately.</p>
+ <h4>
+ Enhanced Callbacks with jQuery Deferred
+ </h4>
+ <p>In JavaScript it is common to invoke functions that optionally accept callbacks that are called within that function. For example, in versions prior to jQuery 1.5, asynchronous processes such as <code>jQuery.ajax()</code> accept callbacks to be invoked some time in the near-future upon success, error, and completion of the ajax request.</p>
+ <p><code>jQuery.Deferred()</code> introduces several enhancements to the way callbacks are managed and invoked. In particular, <code>jQuery.Deferred()</code> provides flexible ways to provide multiple callbacks, and these callbacks can be invoked regardless of whether the original callback dispatch has already occurred. jQuery Deferred is based on the <a href="http://wiki.commonjs.org/wiki/Promises/A">CommonJS Promises/A</a> design.</p>
+ <p>One model for understanding Deferred is to think of it as a chain-aware function wrapper. The <a href="/deferred.then"><code>deferred.then()</code></a>, <a href="/deferred.always"><code>deferred.always()</code></a>, <a href="/deferred.done"><code>deferred.done()</code></a>, and <a href="/deferred.fail"><code>deferred.fail()</code></a> methods specify the functions to be called and the <a href="/deferred.resolve"><code>deferred.resolve(args)</code></a> or <a href="/deferred.reject"><code>deferred.reject(args)</code></a> methods "call" the functions with the arguments you supply. Once the Deferred has been resolved or rejected it stays in that state; a second call to <code>deferred.resolve()</code>, for example, is ignored. If more functions are added by <code>deferred.then()</code>, for example, after the Deferred is resolved, they are called immediately with the arguments previously provided.</p>
+ <p>In most cases where a jQuery API call returns a Deferred or Deferred-compatible object, such as <a href="/jQuery.ajax"><code>jQuery.ajax()</code></a> or <a href="/jQuery.when"><code>jQuery.when()</code></a>, you will only want to use the <a href="/deferred.then"><code>deferred.then()</code></a>, <a href="/deferred.done"><code>deferred.done()</code></a>, and <a href="/deferred.fail"><code>deferred.fail()</code></a> methods to add callbacks to the Deferred's queues. The internals of the API call or code that created the Deferred will invoke <a href="/deferred.resolve"><code>deferred.resolve()</code></a> or <a href="/deferred.reject"><code>deferred.reject()</code></a> on the deferred at some point, causing the appropriate callbacks to run.</p>
+ </longdesc>
+ <category slug="deferred-object"/>
+ <category slug="version/1.5"/>
+</entry>
View
8 pages/Types.html
@@ -84,8 +84,8 @@
<li class="toclevel-1"><a href="#jQuery"><span class="toctext">jQuery</span></a></li>
<li class="toclevel-1"><a href="#XMLHttpRequest"><span class="toctext">XMLHttpRequest</span></a></li>
<li class="toclevel-1"><a href="#jqXHR"><span class="toctext">jqXHR</span></a></li>
- <li class="toclevel-1"><a href="#Deferred"><span class="toctext">Deferred</span></a></li>
- <li class="toclevel-1"><a href="#Promise"><span class="toctext">Promise</span></a></li>
+ <li class="toclevel-1"><a href="#Deferred"><span class="toctext">Deferred Object</span></a></li>
+ <li class="toclevel-1"><a href="#Promise"><span class="toctext">Promise Object</span></a></li>
<li class="toclevel-1"><a href="#Callbacks"><span class="toctext">Callbacks Object</span></a></li>
</ol>
@@ -582,10 +582,10 @@ <h2 id="XMLHttpRequest"> XMLHttpRequest </h2>
<h2 id="jqXHR"> jqXHR </h2>
<p>As of jQuery 1.5, the <a href="http://api.jquery.com/jQuery.ajax/">$.ajax()</a> method returns the jqXHR object, which is a superset of the XMLHTTPRequest object. For more information, see the <a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR section of the $.ajax entry</a>
</p>
-<h2 id="Deferred"> Deferred </h2>
+<h2 id="Deferred"> Deferred Object</h2>
<p>As of jQuery 1.5, the <a href="http://api.jquery.com/category/deferred-object">Deferred</a> object provides a way to register multiple callbacks into self-managed callback queues, invoke callback queues as appropriate, and relay the success or failure state of any synchronous or asynchronous function.</a>
</p>
-<h2 id="Promise"> Promise </h2>
+<h2 id="Promise"> Promise Object</h2>
<p>This object provides a subset of the methods of the <a href="http://api.jquery.com/category/deferred-object">Deferred</a> object (<a href="http://api.jquery.com/deferred.then/"><code>then</code></a>, <a href="http://api.jquery.com/deferred.done/"><code>done</code></a>, <a href="http://api.jquery.com/deferred.fail/"><code>fail</code></a>, <a href="http://api.jquery.com/deferred.always"><code>always</code></a>, <a href="http://api.jquery.com/deferred.pipe/"><code>pipe</code></a>. <a href="http://api.jquery.com/deferred.isResolved/"><code>isResolved</code></a>, and <a href="http://api.jquery.com/deferred.isRejected/"><code>isRejected</code></a>) to prevent users from changing the state of the Deferred.</a>
</p>
<h2 id="Callbacks">Callbacks Object</h2>
Please sign in to comment.
Something went wrong with that request. Please try again.