Arguments accessible by .always(), .done() and .fail() from jQuery.ajax()? #49
Description
Now that .always(), .done() and .fail() are the preferred methods for implementing callbacks from a jQuery.ajax() invocation, and the old methods have been deprecated, it might be a good time to explain the arguments accessible by each of the new methods, and additionally the .then() and .pipe() when applied to jQuery.ajax() invocations?
When browsing the jQuery documentation on api.jquery.com, the available arguments are not listed anywhere, nor are they immediately obvious from elsewhere on the site.
Please would you consider improving the jQuery documentation - for the benefit of other developers who, like myself, cannot see how things work without delving into a debug session? Perhaps you could include the methods clearly within the listing of jQuery.ajax(), noting that the methods are implementations of Deferred and included here for clarity only?
Perhaps you could add a brief section immediately beneath the main properties/functions listing of jQuery.ajax(), showing definitively what arguments are available to each method's callbacks. I am guessing that the arguments are thus, and perhaps this is how they could be shown (once you have confirmed that my guesses are correct!)?:-
_Methods_ (part of jqXHR and Deferred implementations, shown here for clarity only)
.ajax().always(function(a, textStatus, b){});
Replaces method .complete() which was deprecated in jQuery 1.8.
In response to successful transaction, arguments are same as .done() (ie. a = data, b = jqXHR) and for failed transactions the arguments are same as .fail() (ie. a = jqXHR, b = errorThrown).
This is an alternative construct for the complete callback function above. Refer to deferred.always() for implementation details.
.ajax().done(function(data, textStatus, jqXHR){});
Replaces method .success() which was deprecated in jQuery 1.8.
This is an alternative construct for the success callback function above. Refer to deferred.done() for implementation details.
.ajax().fail(function(jqXHR, textStatus, errorThrown){});
Replaces method .error() which was deprecated in jQuery 1.8.
This is an alternative construct for the complete callback function above. Refer to deferred.fail() for implementation details.
.ajax().then(function(data, textStatus, jqXHR){}, function(jqXHR, textStatus, errorThrown){});
Incorporates the functionality of .done() and .fail() methods.
Refer to deferred.then() for implementation details.
.ajax().pipe(function(data, textStatus, jqXHR){}, function(jqXHR, textStatus, errorThrown){});
Incorporates the functionality of .done() and .fail() methods, allowing the underlying Promise to be manipulated.
Refer to deferred.pipe() for implementation details.
My guesswork may be incorrect? This perhaps illustrates the need to improve the documentation within jQuery.ajax().
Hope you can do something to improve documentation.
Kind regards,
Alan
(edited to note that .complete(), .error() and .success() have already been deprecated, and to explain the use of .then() and .pipe() with .ajax())