section Ajax section
Description
Prototype's APIs around the XmlHttpRequest
object.
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 Ajax.Request
.
Request headers
The following headers are sent with all Ajax requests (and can be
overridden with the requestHeaders
option described below):
X-Requested-With
is set toXMLHttpRequest
.X-Prototype-Version
is set to Prototype's current version (e.g.,<%= PROTOTYPE_VERSION %>
).Accept
is set totext/javascript, text/html, application/xml, text/xml, * / *
Content-type
is automatically determined based on thecontentType
andencoding
options.
Ajax options
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.
Common options
asynchronous
(Boolean; defaulttrue
): Determines whetherXMLHttpRequest
is 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.contentType
(String
; defaultapplication/x-www-form-urlencoded
): TheContent-type
header for your request. Change this header if you want to send data in another format (like XML).encoding
(String
; defaultUTF-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.method
(String
; defaultpost
): The HTTP method to use for the request. The other common possibility isget
. Abiding by Rails conventions, Prototype also reacts to other HTTP verbs (such asput
anddelete
) by submitting viapost
and adding a extra_method
parameter with the originally-requested method.parameters
(String
): The parameters for the request, which will be encoded into the URL for aget
method, or into the request body for the other methods. This can be provided either as a URL-encoded string, aHash
, or a plainObject
.postBody
(String
): Specific contents for the request body on apost
method. If it is not provided, the contents of theparameters
option will be used instead.requestHeaders
(Object
): A set of key-value pairs, with properties representing header names.evalJS
(Boolean |String
; defaulttrue
): Automaticallyeval
s the content ofAjax.Response#responseText
and populatesAjax.Response#responseJSON
with it if theContent-type
returned by the server is set toapplication/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, passfalse
.sanitizeJSON
(Boolean; default isfalse
for same-origin requests,true
otherwise): Sanitizes the contents ofAjax.Response#responseText
before evaluating it.
Common callbacks
When used on individual instances, all callbacks (except onException
) are
invoked with two parameters: the Ajax.Response
object and the result of
evaluating the X-JSON
response header, if any (can be null
).
For another way of describing their chronological order and which callbacks
are mutually exclusive, see Ajax.Request
.
onCreate
: Triggered when theAjax.Request
object 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 isundefined
or belongs in the2xy
family. This is skipped if a code-specific callback is defined (e.g.,on200
), and happens beforeonComplete
.onFailure
: Invoked when a request completes and its status code exists but is not in the2xy
family. This is skipped if a code-specific callback is defined (e.g.on403
), and happens beforeonComplete
.onXYZ
(withXYZ
representing 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 ofonSuccess
andonFailure
. Happens beforeonComplete
.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.