Arguments accessible by .always(), .done() and .fail() from jQuery.ajax()?

[alano999]

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())

[roostah]

+1
JQuery documentation is generally quite good - but, this is one area where it needs to be updated.

[AndreasPresthammer]

+1
I'm having the same trouble finding this documentation.

[kswedberg]

I realize this is a glaring omission. Sorry for the delay in updating the documentation. I'll get to it by the end of the week (and if if don't, feel free to scream and holler).

[dalila-taleb]

Screaming and hollering...

I'm going to get the pitchforks :-)

[kswedberg]

Thanks, @dalila-taleb. Working on it now. :)

[peterrow]

Please reopen this - the documentation is still badly formed. The docs for done(), always() etc.. should describe the params for the function. The page for .ajax is already long winded and I missed the above snippet that reproduced in alano999's post.

[kswedberg]

@peterrow It would be really helpful if you could create a new issue and possibly reference this one.

[peterrow]

@kswedberg - done

[axos88]

+1, it should be documented in the always, done, etc as well.

[Flimm]

+1

[xDaizu]

+1

[brenoperucchi]

1+

[ghost]

How can I test the fail scenario of post method.
I am using perl script for on server end.
I have already tried die, exit & return with multiple parameters but I always get success as status.

[dmethvin]

@abhisina That is a StackOverflow question.

[architchandra]

I'm a beginner, so might be wrong, but I am facing a lot of problems trying to understand how to use the methods related to $.ajax and deferred objects. At every step, I'm having to scour StackOverflow. The documentation on these fields is not well-suited for people who already don't have a thorough understanding. Would be grateful if fixed.

[leefogel]

👍

[damien-roche]

Save yourself the headache and use https://github.com/axios/axios.

Been using jQuery for 5 years and yet here I am, yet again scouring for this information.