section Ajax section
Prototype's APIs around the
The Prototype framework enables you to deal with Ajax calls in a manner that is both easy and compatible with all modern browsers.
Actual requests are made by creating instances of
The following headers are sent with all Ajax requests (and can be
overridden with the
requestHeaders option described below):
X-Requested-Withis set to
X-Prototype-Versionis set to Prototype's current version (e.g.,
<%= PROTOTYPE_VERSION %>).
Acceptis set to
Content-typeis automatically determined based on the
All Ajax classes share a common set of options and callbacks. Callbacks are called at various points in the life-cycle of a request, and always feature the same list of arguments.
true): Determines whether
XMLHttpRequestis used asynchronously or not. Synchronous usage is strongly discouraged — it halts all script execution for the duration of the request and blocks the browser UI.
Content-typeheader for your request. Change this header if you want to send data in another format (like XML).
UTF-8): The encoding for the contents of your request. It is best left as-is, but should weird encoding issues arise, you may have to tweak this.
post): The HTTP method to use for the request. The other common possibility is
get. Abiding by Rails conventions, Prototype also reacts to other HTTP verbs (such as
delete) by submitting via
postand adding a extra
_methodparameter with the originally-requested method.
String): The parameters for the request, which will be encoded into the URL for a
getmethod, or into the request body for the other methods. This can be provided either as a URL-encoded string, a
Hash, or a plain
String): Specific contents for the request body on a
postmethod. If it is not provided, the contents of the
parametersoption will be used instead.
Object): A set of key-value pairs, with properties representing header names.
evals the content of
Ajax.Response#responseJSONwith it if the
Content-typereturned by the server is set to
application/json. If the request doesn't obey same-origin policy, the content is sanitized before evaluation. If you need to force evalutation, pass
'force'. To prevent it altogether, pass
sanitizeJSON(Boolean; default is
falsefor same-origin requests,
trueotherwise): Sanitizes the contents of
Ajax.Response#responseTextbefore evaluating it.
When used on individual instances, all callbacks (except
invoked with two parameters: the
Ajax.Response object and the result of
X-JSON response header, if any (can be
For another way of describing their chronological order and which callbacks
are mutually exclusive, see
onCreate: Triggered when the
Ajax.Requestobject is initialized. This is after the parameters and the URL have been processed, but before opening the connection via the 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.
onSuccess: Invoked when a request completes and its status code is
undefinedor belongs in the
2xyfamily. This is skipped if a code-specific callback is defined (e.g.,
on200), and happens before
onFailure: Invoked when a request completes and its status code exists but is not in the
2xyfamily. This is skipped if a code-specific callback is defined (e.g.
on403), and happens before
XYZrepresenting any HTTP status code): Invoked just after the response is complete if the status code is the exact code used in the callback name. Prevents execution of
onFailure. Happens before
onException: Triggered whenever an XHR error arises. Has a custom signature: the first argument is the requester (i.e. an
Ajax.Requestinstance), 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.