Ajax Options
This details all core options (shared by all AJAX requesters) and callbacks.
All requester object in the Ajax
namespace 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. They are passed to requesters right along with their other options.
Common options
Option | Default | Description |
---|---|---|
asynchronous |
true |
Determines whether XMLHttpRequest is used asynchronously or not. Since synchronous usage is rather unsettling, and usually bad taste, you should avoid changing this. Seriously. |
contentType |
'application/x-www-form-urlencoded' |
The Content-Type header for your request. You might want to send XML instead of the regular URL-encoded format, in which case you would have to change this. |
encoding |
'UTF-8' |
The encoding for your request contents. It is best left as is, but should weird encoding issues arise, you may have to tweak it in accordance with other encoding-related parts of your page code and server side. |
method |
'post' |
The HTTP method to use for the request. The other widespread possibility is 'get' . As a Ruby On Rails special, Prototype also reacts to other verbs (such as 'put' and 'delete' by actually using 'post' and putting an extra '_method' parameter with the originally requested method in there. |
parameters |
'' |
The parameters for the request, which will be encoded into the URL for a 'get' method, or into the request body for the other methods. This can be provided either as a URL-encoded string or as any Hash -compatible object (basically anything), with properties representing parameters. |
postBody |
None | Specific contents for the request body on a 'post' method (actual method, after possible conversion as described in the method opt
ion above). If it is not provided, the contents of the parameters option will be used instead. |
requestHeaders |
See text |
Request headers can be passed under two forms:
Prototype automatically provides a set of default headers, that this option can override and augment:
|
evalJS |
true | Automatically evals the content of Ajax.Response#responseText if the content-type returned by the server is one of the following: application/ecmascript ,
application/javascript ,
application/x-ecmascript ,
application/x-javascript ,
text/ecmascript ,
text/javascript ,
text/x-ecmascript , or
text/x-javascript and the request obeys SOP. If you need to force evalutation, pass 'force' . To prevent it altogether, pass false . |
evalJSON |
true | Automatically evals the content of Ajax.Response#responseText and populates Ajax.Response#responseJSON with it if the content-type returned by the server is set to application/json . If the request doesn't obey SOP, the content is sanitized before evaluation. If you need to force evalutation, pass 'force' . To prevent it altogether, pass false . |
sanitizeJSON |
false for local requests, true otherwise. |
Sanitizes the content of Ajax.Response#responseText before evaluating it. |
Common callbacks
When used on individual instances, all callbacks (except onException
) are invoked with two parameters: the XMLHttpRequest
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
.
Callback | Description |
---|---|
onCreate (v1.5.1) |
Triggered when the Ajax.Request object is initialized. This is after the parameters and the URL have been processed, but before first using the methods of the XHR object. |
onComplete |
Triggered at the very end of a request's life-cycle, once the request completed, status-specific callbacks were called, and possible automatic behaviors were processed. |
onException |
Triggered whenever an XHR error arises. Has a custom signature: the first argument is the requester (i.e. an Ajax.Request instance), the second is the exception object. |
onFailure |
Invoked when a request completes and its status code exists but is not in the 2xy family. This is skipped if a code-specific callback is defined, and happens before onComplete . |
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. |
onLoaded |
(Not guaranteed) Triggered once the underlying XHR object is setup, the connection open, and ready to send its actual request. |
onLoading |
(Not guaranteed) Triggered when the underlying XHR object is being setup, and its connection opened. |
onSuccess |
Invoked when a request completes and its status code is undefined or belongs in the 2xy family. This is skipped if a code-specific callback is defined, and happens before onComplete . |
onUninitialized |
(Not guaranteed) Invoked when the XHR object was just created. |
on XYZ |
With XYZ being an HTTP status code for the response. Invoked when the response just completed, and the status code is exactly the one we used in t
he callback name. Prevents execution of onSuccess / onFailure . Happens before onComplete . |
Responder callbacks
When used on responders, all callbacks (except onException
and onCreate
) are invoked with three parameters: the requester (i.e. the corresponding "instance" of Ajax.Request
) object, 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.
Callback | Description | |
---|---|---|
onCreate |
Triggered whenever a requester object from the Ajax namespace is created, after its parameters where adjusted and its before its XHR connection is opened. This takes two arguments: the requester object and the underlying XHR object. | |
onComplete |
Triggered at the very end of a request's life-cycle, once the request completed, status-specific callbacks were called, and possible automatic behaviors were processed. | |
onException |
Triggered whenever an XHR error arises. Has a custom signature: the first argument is the requester (i.e. an Ajax.Request instance), the second is the exception object. |
|
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. | |
onLoaded |
(Not guaranteed) Triggered once the underlying XHR object is setup, the connection open, and ready to send its actual request. | |
onLoading |
(Not guaranteed) Triggered when the underlying XHR object is being setup, and its connection opened. | |
onUninitialized |
(Not guaranteed) Invoked when the XHR object was just created. |