In the wake of using the Yahoo! User Interface Library to wrap AJAX1 requests for the SPARQL calendar demo, I decided to try out the Prototype JavaScript framework for my latest round of (unrelated) web hacking.
Very early on, I was struck by an incongruency between the callback signatures of the onSuccess, onFailure, and on### events and those of the onLoading, onLoaded, onComplete, etc. events. Event handlers for the former collection of events—which only occur after a request is completed—receive two arguments: the XMLHttpRequest object itself, and, if applicable, a JavaScript object formed by parsing the JSON serialized value of any X-JSON response header.
On the other hand, event handlers for the latter set of events (events that correspond to ready-state changes), receive the above two arguments and in addition receive the Ajax.Request wrapper object that was used in the creation of the AJAX request. In turn, this object gives access to the options dictionary, which can contain arbitrary bits of state useful in routing callbacks to their eventual final destination(s).
Why don't the other callbacks contain the Ajax.Request objects? Got me. Maybe for compatibility with some other (unknown) API? In any case, I hacked around this in my application by duplicating the functionality from prototype.js that translates generic onComplete events into specific onSuccess and onFailure events:
... onComplete: function(request, xhr, xjson) { if (request.responseIsSuccess()) this._onSuccess(request, xhr, xjson); else this._onFailure(request, xhr, xjson); }, ..._onSuccess and _onFailure act just as regular ol' onSuccess and onFailure would, except that they now have access to the original Ajax.Request object. Good enough for me, but curious nonetheless.
1 AJAX sure has used its snazzy-name status to propel a not-so-novel idea to stratospheric levels of buzzwordiness. The lack of a consistent capitalization for it (AJAX vs. Ajax) bugs the heck out of me though. Of course, it really should be AJaX, but I doubt that will ever catch on. Alas.