search

jquery / api.jquery.com

API documentation for jQuery Core
https://api.jquery.com
Other
318 stars 266 forks source link

Clarify usage of ajax events with .on() #503

Open dmethvin opened 10 years ago

dmethvin commented 10 years ago

The docs don't mention that .ajaxComplete() et al are actually aliases for triggered/triggerable events that can be attached with .on(),

Also, the language on these pages and the http://api.jquery.com/Ajax_Events/ page should be clarified now that the term "global event" doesn't apply. These events are triggered on document only. The Ajax Events page says the error and success callbacks are "local events" but that is confusing nomenclature, they aren't events in the DOM-event sense of the word.

dmethvin commented 10 years ago

List of all ajax event names are in https://github.com/jquery/jquery/blob/master/src%2Fevent%2Fajax.js

kswedberg commented 10 years ago

@dmethvin : Great points. I'm gonna take a stab at updating this page. I was thinking about starting with the true events. Then mention error, success, et al as " callback options". Might as well mention promise methods, too, while we're at it—at least for the order of execution, if that can be determined.

I think we're referring to "global" versus "local" in the sense that global happens for all requests, not in the sense of being able to apply it to any DOM element. Also, $.ajax() has a global setting that turns off these events, so I think it makes sense to continue referring to them as global. Thoughts?

dmethvin commented 10 years ago

Using "callback options" sounds good to me. As far as the order of execution of everything, I don't know that we want to define all that. "People shouldn't be mixing promises, callbacks, and events in ways that depend on order," he pontificated. :question:

kswedberg commented 10 years ago

ok. Do you think it makes sense to still refer to "global events," though, given the global setting?

dmethvin commented 10 years ago

I guess we can define "global" as "triggered on the global document object" perhaps?

arthurvr commented 9 years ago

Great points. I'm gonna take a stab at updating this page.

@kswedberg Are you still interested in taking this (or already working on it)?

kswedberg commented 9 years ago

@arthurvr : oh boy, I think I've littered this repo with a million little promises like that. I keep thinking I'm going to find time right around the corner, but I discover that I have less and less. Please feel free to take this on if you're willing and able.