Prototype - AJAX Options



This is Ajax namespace which 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 Description
asynchronous

Default value is true.

Determines whether XMLHttpRequest is used asynchronously or not.

contentType

Default value is application/x-www-form-urlencoded.

The Content-Type header for your request.

encoding

Default value is UTF-8.

The Content-Type header for your request.

method

Default value is post.

The HTTP method to use for the request.

parameters

Default value is ' '.

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 with properties representing parameters.

postBody

Default value is None.

Specific contents for the request body on a 'post' method. If it is not provided, the contents of the parameters option will be used instead.

requestHeaders

See description below.

Request headers can be passed under two forms −

  • As an object, with properties representing headers.

  • As an array, with even-index (0, 2...) elements being header names, and odd-index (1, 3...) elements being values.

Prototype automatically provides a set of default headers, that this option can override and augment −

  • X-Requested-With is set to 'XMLHttpRequest'.

  • X-Prototype-Version provides Prototype's current version (e.g. 1.5.0).

  • Accept defaults to 'text/javascript, text/html, application/xml, text/xml, */*'

  • Content-type is built based on the contentType and encoding options.

evalJS

Default value is 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, (Simple Origin Policy). If you need to force evalutation, pass 'force'. To prevent it altogether, pass false.

evalJSON

Default value is 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

S.No. Callback & Description
1.

onCreate

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.

2.

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.

3.

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.

4.

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.

5.

onInteractive

Not guaranteed but triggered whenever the requester receives a part of the response (but not the final part), should it be sent in several packets.

6.

onLoaded

Not guaranteed but triggered once the underlying XHR object is setup, the connection open, and ready to send its actual request.

7.

onLoading

Not guaranteed but triggered when the underlying XHR object is being setup, and its connection opened.

8.

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

9.

onUninitialized

Not guaranteed but invoked when the XHR object was just created.

10.

onXYZ

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

S.No. Callback & Description
1.

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.

2.

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.

3.

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.

4.

onInteractive

Not guaranteed but riggered whenever the requester receives a part of the response (but not the final part), should it be sent in several packets.

5.

onLoaded

Not guaranteed but triggered once the underlying XHR object is setup, the connection open, and ready to send its actual request.

6.

onLoading

Not guaranteed but triggered when the underlying XHR object is being setup, and its connection opened.

7.

onUninitialized

Not guaranteed but invoked when the XHR object was just created.

prototype_ajax_tutorial.htm
Advertisements