<?xml version='1.0' encoding='ISO-8859-1'?>
<?xml-stylesheet type='text/xsl' href='docs.xsl'?>
<docs>
<method cat='Ajax' type='XMLHttpRequest' see='ajaxSetup(Map)' short='Load a remote page using an HTTP request.' name='$.ajax'>
<desc>Load a remote page using an HTTP request.

This is jQuery's low-level AJAX implementation. See $.get, $.post etc. for
higher-level abstractions that are often easier to understand and use,
but don't offer as much functionality (such as error callbacks).

$.ajax() returns the XMLHttpRequest that it creates. In most cases you won't
need that object to manipulate directly, but it is available if you need to
abort the request manually.

'''Note:''' If you specify the dataType option described below, make sure
the server sends the correct MIME type in the response (eg. xml as "text/xml").
Sending the wrong MIME type can lead to unexpected problems in your script.
See [[Specifying the Data Type for AJAX Requests]] for more information.

Supported datatypes are (see dataType option):

"xml": Returns a XML document that can be processed via jQuery.

"html": Returns HTML as plain text, included script tags are evaluated.

"script": Evaluates the response as Javascript and returns it as plain text.

"json": Evaluates the response as JSON and returns a Javascript Object

$.ajax() takes one argument, an object of key/value pairs, that are
used to initalize and handle the request. These are all the key/values that can
be used:

(String) url - The URL to request.

(String) type - The type of request to make ("POST" or "GET"), default is "GET".

(String) dataType - The type of data that you're expecting back from
the server. No default: If the server sends xml, the responseXML, otherwise
the responseText is passed to the success callback.

(Boolean) ifModified - Allow the request to be successful only if the
response has changed since the last request. This is done by checking the
Last-Modified header. Default value is false, ignoring the header.

(Number) timeout - Local timeout to override global timeout, eg. to give a
single request a longer timeout while all others timeout after 1 second.
See $.ajaxTimeout() for global timeouts.

(Boolean) global - Whether to trigger global AJAX event handlers for
this request, default is true. Set to false to prevent that global handlers
like ajaxStart or ajaxStop are triggered.

(Function) error - A function to be called if the request fails. The
function gets passed tree arguments: The XMLHttpRequest object, a
string describing the type of error that occurred and an optional
exception object, if one occured.

(Function) success - A function to be called if the request succeeds. The
function gets passed one argument: The data returned from the server,
formatted according to the 'dataType' parameter.

(Function) complete - A function to be called when the request finishes. The
function gets passed two arguments: The XMLHttpRequest object and a
string describing the type of success of the request.

(Object|String) data - Data to be sent to the server. Converted to a query
string, if not already a string. Is appended to the url for GET-requests.
See processData option to prevent this automatic processing.

(String) contentType - When sending data to the server, use this content-type.
Default is "application/x-www-form-urlencoded", which is fine for most cases.

(Boolean) processData - By default, data passed in to the data option as an object
other as string will be processed and transformed into a query string, fitting to
the default content-type "application/x-www-form-urlencoded". If you want to send
DOMDocuments, set this option to false.

(Boolean) async - By default, all requests are sent asynchronous (set to true).
If you need synchronous requests, set this option to false.

(Function) beforeSend - A pre-callback to set custom headers etc., the
XMLHttpRequest is passed as the only argument.</desc>
<params type='Map' name='properties'>
<desc>Key/value pairs to initialize the request with.</desc>
</params>
<examples>
<desc>Load and execute a JavaScript file.</desc>
<code>$.ajax({
  type: "GET",
  url: "test.js",
  dataType: "script"
})</code>
</examples>
<examples>
<desc>Save some data to the server and notify the user once its complete.</desc>
<code>$.ajax({
  type: "POST",
  url: "some.php",
  data: "name=John&amp;location=Boston",
  success: function(msg){
    alert( "Data Saved: " + msg );
  }
});</code>
</examples>
<examples>
<desc>Loads data synchronously. Blocks the browser while the requests is active.
It is better to block user interaction by other means when synchronization is
necessary.</desc>
<code>var html = $.ajax({
 url: "some.php",
 async: false
}).responseText;</code>
</examples>
<examples>
<desc>Sends an xml document as data to the server. By setting the processData
option to false, the automatic conversion of data to strings is prevented.</desc>
<code>var xmlDocument = [create xml document];
$.ajax({
  url: "page.php",
  processData: false,
  data: xmlDocument,
  success: handleResponse
});</code>
</examples>
</method></docs>
