entries/deferred.done.xml

<?xml version="1.0"?>
<entry name="deferred.done" type="method" return="Deferred">
  <title>deferred.done()</title>
  <signature>
    <added>1.5</added>
    <argument name="doneCallbacks" type="Function">
      <desc>
        A function, or array of functions, that are called when the Deferred is resolved.
      </desc>
    </argument>
    <argument name="doneCallbacks" type="Function" optional="true">
      <desc>
        Optional additional functions, or arrays of functions, that are called when the Deferred is resolved.
      </desc>
    </argument>
  </signature>
  <desc> Add handlers to be called when the Deferred object is resolved. </desc>
  <longdesc>
    <p>The <code>deferred.done()</code> method accepts one or more arguments, all of which can be either a single function or an array of functions. When the Deferred is resolved, the doneCallbacks are called. Callbacks are executed in the order they were added. Since <code>deferred.done()</code> returns the deferred object, other methods of the deferred object can be chained to this one, including additional <code>.done()</code> methods. When the Deferred is resolved, doneCallbacks are executed using the arguments provided to the <a href="/deferred.resolve/"><code>resolve</code></a> or <a href="/deferred.resolveWith/"><code>resolveWith</code></a> method call in the order they were added. For more information, see the documentation for <a href="/category/deferred-object/">Deferred object</a>.</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 a success callback using the <code>.done()</code> method.</desc>
    <code><![CDATA[
$.get( "test.php" ).done(function() {
  alert( "$.get succeeded" );
});
]]></code>
  </example>
  <example>
    <desc>Resolve a Deferred object when the user clicks a button, triggering a number of callback functions:</desc>
    <code><![CDATA[
// 3 functions to call when the Deferred object is resolved
function fn1() {
  $( "p" ).append( " 1 " );
}
function fn2() {
  $( "p" ).append( " 2 " );
}
function fn3( n ) {
  $( "p" ).append( n + " 3 " + n );
}

// Create a deferred object
var dfd = $.Deferred();

// Add handlers to be called when dfd is resolved
dfd
// .done() can take any number of functions or arrays of functions
  .done( [ fn1, fn2 ], fn3, [ fn2, fn1 ] )
// We can chain done methods, too
  .done(function( n ) {
    $( "p" ).append( n + " we're done." );
  });

// Resolve the Deferred object when the button is clicked
$( "button" ).on( "click", function() {
  dfd.resolve( "and" );
});
]]></code>
    <html><![CDATA[
<button>Go</button>
<p>Ready...</p>
]]></html>
  </example>
  <category slug="deferred-object"/>
  <category slug="version/1.5"/>
</entry>