prototype/src/ajax.js

/**
 *  == Ajax ==
 *  
 *  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]].
 *  
 *  <h4>Request headers</h4>
 *  
 *  The following headers are sent with all Ajax requests (and can be
 *  overridden with the `requestHeaders` option described below):
 *  
 *  * `X-Requested-With` is set to `XMLHttpRequest`.
 *  * `X-Prototype-Version` is set to Prototype's current version (e.g.,
 *    `1.6.0.3`).
 *  * `Accept` is set to `text/javascript, text/html, application/xml,
 *     text/xml, * / *`
 *  * `Content-type` is automatically determined based on the `contentType`
 *    and `encoding` options.
 *  
 *  <h4>Ajax options</h4>
 *  
 *  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.
 *  
 *  <h5>Common options</h5>
 *  
 *  * `asynchronous` ([[Boolean]]; default `true`): Determines whether
 *    `XMLHttpRequest` is used asynchronously or not. Synchronous usage is
 *    seriously 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 `eval`s
 *    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.
 *  
 *  <h4>Common callbacks</h4>
 *  
 *  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]].
 *  
 *  * `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. _Prevents_ execution 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.
 *  
**/

//= require "ajax/ajax"
//= require "ajax/responders"
//= require "ajax/base"
//= require "ajax/request"
//= require "ajax/response"
//= require "ajax/updater"
//= require "ajax/periodical_updater"