Where is the Ajax.Request options documentation?

[Adam Nielsen]

Hi all,

If I go to the Prototype documentation and click on Ajax.Request, it gives me a nice summary with a few basic examples.

On that page it says "As you can see under the "Ajax options" heading of the Ajax, Prototype's AJAX objects define a whole slew of callbacks" - however on that URL I can't see any documentation about the available options.

If instead I look at the Ajax.Request constructor documentation, it says about the options parameter "Configuration for the request. See the Ajax for more information."  The link just goes back to the main Ajax page where I can't see any info about the available options.

Am I missing something, or is there no documentation about the Ajax.Request options?

Thanks,
Adam.

[Christophe Decaux]

Hi there,

Just click on the « Ajax section » header in the left column (the black one). That will link you to : http://prototypejs.org/doc/latest/ajax/

In there, you’ll find what you’re looking for…

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; default true): Determines whether XMLHttpRequest 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; default application/x-www-form-urlencoded): The Content-type header for your request. Change this header if you want to send data in another format (like XML).
• encoding (String; default 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.
• method (String; default 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 put and delete) by submitting via post 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 a get method, or into the request body for the other methods. This can be provided either as a URL-encoded string, a Hash, or a plain Object.
• postBody (String): 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 (Object): A set of key-value pairs, with properties representing header names.
• evalJS (Boolean | String; default true): Automatically evals the content of Ajax.Response#responseText if the Content-type returned by the server is set to one of text/javascript, application/ecmascript (matches expression (text|application)\/(x-)?(java|ecma)script). If the request doesn't obey same-origin policy, the content is not evaluated. If you need to force evalutation, pass 'force'. To prevent it altogether, pass false.
• evalJSON (Boolean | String; default 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 same-origin policy, the content is sanitized before evaluation. If you need to force evalutation, pass 'force'. To prevent it altogether, pass false.
• sanitizeJSON (Boolean; default is false for same-origin requests, true otherwise): Sanitizes the contents of Ajax.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-JSONresponse 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 the Ajax.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 is undefined or belongs in the 2xy family. This is skipped if a code-specific callback is defined (e.g., on200), and happens before onComplete.
• 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 (e.g. on403), and happens before onComplete.
• onXYZ (with XYZ 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. Preventsexecution of onSuccess and onFailure. Happens before onComplete.
• onException: Triggered whenever an XHR error arises. Has a custom signature: the first argument is the requester (i.e. an Ajax.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.

Enjoy,

Christophe

--
You received this message because you are subscribed to the Google Groups "Prototype & script.aculo.us" group.
To unsubscribe from this group and stop receiving emails from it, send an email to prototype-scripta...@googlegroups.com.
To post to this group, send email to prototype-s...@googlegroups.com.
Visit this group at https://groups.google.com/group/prototype-scriptaculous.
For more options, visit https://groups.google.com/d/optout.

[Adam Nielsen]

Just click on the « Ajax section » header in the left column (the black one). That will link you to : http://prototypejs.org/doc/latest/ajax/

In there, you’ll find what you’re looking for…

Ah, that's what I'm looking for!  Many thanks.

Cheers,
Adam.