control-freak-ide/Control-Freak-Documentation/jQuery/docs/entries/deferred.then.json

{"name":"deferred.then","type":"method","title":"deferred.then()","deprecated":null,"removed":null,"desc":"Add handlers to be called when the Deferred object is resolved, rejected, or still in progress. ","categories":["deferred-object","version/1.5","version/1.7"],"entries":[{"return":"Promise","signatures":[{"added":"1.8","argument":[{"desc":"\n        A function that is called when the Deferred is resolved.\n      ","name":"doneFilter","type":"Function"},{"desc":"\n        An optional function that is called when the Deferred is rejected.\n      ","name":"failFilter","type":"Function","optional":"true"},{"desc":"\n        An optional function that is called when progress notifications are sent to the Deferred.\n      ","name":"progressFilter","type":"Function","optional":"true"}]},{"added":"1.5","removed":"1.8","argument":[{"desc":"\n        A function, or array of functions, called when the Deferred is resolved.\n      ","name":"doneCallbacks","type":"Function"},{"desc":"\n        A function, or array of functions, called when the Deferred is rejected.\n      ","name":"failCallbacks","type":"Function"}]},{"added":"1.7","removed":"1.8","argument":[{"desc":"\n        A function, or array of functions, called when the Deferred is resolved.\n      ","name":"doneCallbacks","type":"Function"},{"desc":"\n        A function, or array of functions, called when the Deferred is rejected.\n      ","name":"failCallbacks","type":"Function"},{"desc":"\n        A function, or array of functions, called when the Deferred notifies progress.\n      ","name":"progressCallbacks","type":"Function","optional":"true"}]}],"examples":[{"desc":"Since the <ahref=\"/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.","code":"\n$.get( \"test.php\" ).then(\n  function() {\n    alert( \"$.get succeeded\" );\n  }, function() {\n    alert( \"$.get failed!\" );\n  }\n);\n"},{"desc":"Filter the resolve value:","html":"\n<button>Filter Resolve</button>\n<p></p>\n","code":"\nvar filterResolve = function() {\n  var defer = $.Deferred(),\n    filtered = defer.then(function( value ) {\n      return value * 2;\n    });\n\n  defer.resolve( 5 );\n  filtered.done(function( value ) {\n    $( \"p\" ).html( \"Value is ( 2*5 = ) 10: \" + value );\n  });\n};\n\n$( \"button\" ).on( \"click\", filterResolve );\n"},{"desc":"Filter reject value:","code":"\nvar defer = $.Deferred(),\n  filtered = defer.then( null, function( value ) {\n    return value * 3;\n  });\n\ndefer.reject( 6 );\nfiltered.fail(function( value ) {\n  alert( \"Value is ( 3*6 = ) 18: \" + value );\n});\n"},{"desc":"Chain tasks:","code":"\nvar request = $.ajax( url, { dataType: \"json\" } ),\n  chained = request.then(function( data ) {\n    return $.ajax( url2, { data: { user: data.userId } } );\n  });\n\nchained.done(function( data ) {\n  // data retrieved from url2 as provided by the first request\n});\n"}],"longdesc":"\n    <p><strong>Prior to jQuery 1.8</strong>, the arguments could be a function or an array of functions.</p>\n    <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>\n\n    <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>\n\n    <p>Callbacks are executed in the order they were added. Since\n      <code>deferred.then</code> returns a Promise, other methods of the\n      Promise object can be chained to this one, including additional\n      <code>.then()</code> methods.\n    </p>\n  "}]}