namespace Ajax.Responders
Description
A repository of global listeners notified about every step of Prototype-based Ajax requests.
Sometimes, you need to provide generic behaviors over all Ajax operations
happening on the page (through Ajax.Request
, Ajax.Updater
or
Ajax.PeriodicalUpdater
).
For instance, you might want to automatically show an indicator when an Ajax request is ongoing, and hide it when none are. You may well want to factor out exception handling as well, logging those somewhere on the page in a custom fashion. The possibilities are myriad.
To achieve this, Prototype provides Ajax.Responders
, which lets you
register (and, if you wish, unregister later) responders, which are
objects with specially-named methods. These names come from a set of
general callbacks corresponding to different points in time (or outcomes)
of an Ajax request's life cycle.
For instance, Prototype automatically registers a responder that maintains
a nifty variable: Ajax.activeRequestCount
. This represents, at a given
time, the number of currently active Ajax requests — by monitoring their
onCreate
and onComplete
events. The code for this is fairly simple:
Ajax.Responders.register({
onCreate: function() {
Ajax.activeRequestCount++;
},
onComplete: function() {
Ajax.activeRequestCount--;
}
});
Responder callbacks
The callbacks for responders are similar to the callbacks described in
the Ajax, but take a different signature. They're invoked with
three parameters: the requester object (i.e., the corresponding "instance"
of Ajax.Request
), the XMLHttpRequest
object, and the result of
evaluating the X-JSON
response header, if any (can be null
). They also
execute in the context of the responder, bound to the this
reference.
onCreate
: Triggered whenever a requester object from theAjax
namespace is created, after its parameters are adjusted and before its XHR connection is opened. This takes two arguments: the requester object and the underlying XHR object.onUninitialized
(Not guaranteed): Invoked just after the XHR object is created.onLoading
(Not guaranteed): Triggered when the underlying XHR object is being setup, and its connection opened.onLoaded
(Not guaranteed): Triggered once the underlying XHR object is setup, the connection is open, and it is ready to send its actual request.onInteractive
(Not guaranteed): Triggered whenever the requester receives a part of the response (but not the final part), should it be sent in several packets.onException
: Triggered whenever an XHR error arises. Has a custom signature: the first argument is the requester (i.e. anAjax.Request
instance), and the second is the exception object.onComplete
: Triggered at the very end of a request's life-cycle, after the request completes, status-specific callbacks are called, and possible automatic behaviors are processed. Guaranteed to run regardless of what happened during the request.