From jQuery JavaScript Library

$.ajax( properties )

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 instance 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.

Data Types and $.ajax

$.ajax gives you the option to specify a dataType parameter, which gives jQuery a hint as to what to expect back from the server. Based on this hint, jQuery processes the response data and passes it as the first argument to your success callback function (if provided). You may specify the dataType as a key/value pair in the lone argument passed to $.ajax. Supported types are:

• "xml": Returns an 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

Note: Make sure the server handling the request sends the right MIME type (eg. xml as "text/xml"). That is, if you specify the dataType option to be "xml", make sure your server sends content with the "text/xml" MIME type. Sending the wrong MIME type will prohibit jQuery from correctly managing the data returned in the response, and could cause unexpected problems in your script.

Calling $.ajax

$.ajax() takes one argument, an object of key/value pairs, that are used to initalize and handle the request, and returns the XMLHttpRequest object for post-processing (like manual aborting) if needed.

Options: Several options that control the behavior of $.ajax are available. They are specified as key/value pairs of the 'parameters' object passed to $.ajax:

• (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. If none is specified, jQuery will intelligently pass either responseXML or responseText to your success callback, based on the MIME type of the response. If "xml" is in the MIME type, jQuery will pass the responseXML to your callback, otherwise you'll get the responseText.

• (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 - Set a local timeout for the request. This will override the global timeout, if one is set via $.ajaxTimeout. For example, you could use this property to give a single request a longer timeout than all other requests that you've set to time out in one second. See $.ajaxTimeout() for global timeouts.

• (Boolean) global - Whether to trigger global AJAX event handlers for this request. The default is true. Set to false to prevent the global handlers like ajaxStart or ajaxStop from being triggered.

• (Function) error - A function to be called if the request fails. The function gets passed three 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 (after success and error callbacks are executed). 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. It is 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 (technically, anything other than a 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 or other non-processed data, set this option to false.

• (Boolean) async - By default, all requests are send asynchronous (set to true). If you need synchronous requests, set this option to false. Note that synchronous requests may temporarily lock the browser, disabling any actions while the request is active.

• (Function) beforeSend - A pre-callback to modify the XMLHttpRequest object before it is sent. Use this to set custom headers in the request, for example. The XMLHttpRequest is passed as the only argument.

Return value: XMLHttpRequest
Parameters:

• properties (Map): Key/value pairs to initialize the request with.

Example:

 $.ajax({
   type: "GET",
   url: "test.js",
   dataType: "script"
 })

Example:

 $.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });

Example:

 var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;

Example:

 var xmlDocument = [create xml document];
 $.ajax({
   url: "page.php",
   processData: false,
   data: xmlDocument,
   success: handleResponse
 });

$.ajaxSetup( settings )

Setup global settings for AJAX requests.

See $.ajax for a description of all available options.

Return value: undefined
Parameters:

• settings (Map): Key/value pairs to use for all AJAX requests

Example:

 $.ajaxSetup( {
   url: "/xmlhttp/",
   global: false,
   type: "POST"
 } );
 $.ajax({ data: myData });

$.ajaxTimeout( time )

Set the timeout of all AJAX requests to a specific amount of time. This will make all future AJAX requests timeout after a specified amount of time.

Set to null or 0 to disable timeouts (default).

You can manually abort requests with the XMLHttpRequest's (returned by all ajax functions) abort() method.

Deprecated. Use $.ajaxSetup instead.

Return value: undefined
Parameters:

• time (Number): How long before an AJAX request times out.

Example:

 $.ajaxTimeout( 5000 );

$.get( url, params, callback )

Load a remote page using an HTTP GET request. This is an easier way of sending a simple GET request to a server without having to use the more complex $.ajax function. It allows a single callback function to be specified that will be executed when the request is complete (technically, only if the response is successful).

Return value: XMLHttpRequest
Parameters:

• url (String): The URL of the page to load.
• params (Map): (optional) Key/value pairs that will be sent to the server.
• callback (Function): (optional) A function to be executed whenever the data is loaded successfully.

Example:

 $.get("test.cgi");

Example:

 $.get("test.cgi", { name: "John", time: "2pm" } );

Example:

 $.get("test.cgi", function(data){
   alert("Data Loaded: " + data);
 });

Example:

 $.get("test.cgi",
   { name: "John", time: "2pm" },
   function(data){
     alert("Data Loaded: " + data);
   }
 );

$.getIfModified( url, params, callback )

Load a remote page using an HTTP GET request, only if it hasn't been modified since it was last retrieved.

Return value: XMLHttpRequest
Parameters:

• url (String): The URL of the page to load.
• params (Map): (optional) Key/value pairs that will be sent to the server.
• callback (Function): (optional) A function to be executed whenever the data is loaded.

Example:

 $.getIfModified("test.html");

Example:

 $.getIfModified("test.html", { name: "John", time: "2pm" } );

Example:

 $.getIfModified("test.cgi", function(data){
   alert("Data Loaded: " + data);
 });

Example:

 $.getifModified("test.cgi",
   { name: "John", time: "2pm" },
   function(data){
     alert("Data Loaded: " + data);
   }
 );

$.getJSON( url, params, callback )

Load JSON data using an HTTP GET request.

Return value: XMLHttpRequest
Parameters:

• url (String): The URL of the page to load.
• params (Map): (optional) Key/value pairs that will be sent to the server.
• callback (Function): A function to be executed whenever the data is loaded.

Example:

 $.getJSON("test.js", function(json){
   alert("JSON Data: " + json.users[3].name);
 });

Example:

 $.getJSON("test.js",
   { name: "John", time: "2pm" },
   function(json){
     alert("JSON Data: " + json.users[3].name);
   }
 );

$.getScript( url, callback )

Loads, and executes, a remote JavaScript file using an HTTP GET request.

Warning: Safari <= 2.0.x is unable to evalulate scripts in a global context synchronously. If you load functions via getScript, make sure to call them after a delay.

Return value: XMLHttpRequest
Parameters:

• url (String): The URL of the page to load.
• callback (Function): (optional) A function to be executed whenever the data is loaded.

Example:

 $.getScript("test.js");

Example:

 $.getScript("test.js", function(){
   alert("Script loaded and executed.");
 });

$.post( url, params, callback )

Load a remote page using an HTTP POST request. This is an easier way of sending a simple POST request to a server without having to use the more complex $.ajax function. It allows a single callback function to be specified that will be executed when the request is complete (technically, only if the response is successful).

Return value: XMLHttpRequest
Parameters:

• url (String): The URL of the page to load.
• params (Map): (optional) Key/value pairs that will be sent to the server.
• callback (Function): (optional) A function to be executed whenever the data is loaded successfully.

Example:

 $.post("test.cgi");

Example:

 $.post("test.cgi", { name: "John", time: "2pm" } );

Example:

 $.post("test.cgi", function(data){
   alert("Data Loaded: " + data);
 });

Example:

 $.post("test.cgi",
   { name: "John", time: "2pm" },
   function(data){
     alert("Data Loaded: " + data);
   }
 );

ajaxComplete( callback )

Attach a function to be executed whenever an AJAX request completes.

The XMLHttpRequest and settings used for that request are passed as arguments to the callback.

Return value: jQuery
Parameters:

• callback (Function): The function to execute.

Example:

 $("#msg").ajaxComplete(function(request, settings){
   $(this).append("<li>Request Complete.</li>");
 });

ajaxError( callback )

Attach a function to be executed whenever an AJAX request fails.

The XMLHttpRequest and settings used for that request are passed as arguments to the callback. A third argument, an exception object, is passed if an exception occured while processing the request.

Return value: jQuery
Parameters:

• callback (Function): The function to execute.

Example:

 $("#msg").ajaxError(function(request, settings){
   $(this).append("<li>Error requesting page " + settings.url + "</li>");
 });

ajaxSend( callback )

Attach a function to be executed before an AJAX request is send.

The XMLHttpRequest and settings used for that request are passed as arguments to the callback.

Return value: jQuery
Parameters:

• callback (Function): The function to execute.

Example:

 $("#msg").ajaxSend(function(request, settings){
   $(this).append("<li>Starting request at " + settings.url + "</li>");
 });

ajaxStart( callback )

Attach a function to be executed whenever an AJAX request begins and there is none already active.

Return value: jQuery
Parameters:

• callback (Function): The function to execute.

Example:

 $("#loading").ajaxStart(function(){
   $(this).show();
 });

ajaxStop( callback )

Attach a function to be executed whenever all AJAX requests have ended.

Return value: jQuery
Parameters:

• callback (Function): The function to execute.

Example:

 $("#loading").ajaxStop(function(){
   $(this).hide();
 });

ajaxSuccess( callback )

Attach a function to be executed whenever an AJAX request completes successfully.

The XMLHttpRequest and settings used for that request are passed as arguments to the callback.

Return value: jQuery
Parameters:

• callback (Function): The function to execute.

Example:

 $("#msg").ajaxSuccess(function(request, settings){
   $(this).append("<li>Successful Request!</li>");
 });

load( url, params, callback )

Load HTML from a remote file and inject it into the DOM.

Note: Avoid to use this to load scripts, instead use $.getScript. IE strips script tags when there aren't any other characters in front of it.

Return value: jQuery
Parameters:

• url (String): The URL of the HTML file to load.
• params (Object): (optional) A set of key/value pairs that will be sent as data to the server.
• callback (Function): (optional) A function to be executed whenever the data is loaded (parameters: responseText, status and response itself).

Example:

 $("#feeds").load("feeds.html");

 <div id="feeds"></div>

 <div id="feeds"><b>45</b> feeds found.</div>

Example:

 $("#feeds").load("feeds.html",
   {limit: 25},
   function() { alert("The last 25 entries in the feed have been loaded"); }
 );

loadIfModified( url, params, callback )

Load HTML from a remote file and inject it into the DOM, only if it's been modified by the server.

Return value: jQuery
Parameters:

• url (String): The URL of the HTML file to load.
• params (Map): (optional) Key/value pairs that will be sent to the server.
• callback (Function): (optional) A function to be executed whenever the data is loaded (parameters: responseText, status and response itself).

Example:

 $("#feeds").loadIfModified("feeds.html");

 <div id="feeds"></div>

 <div id="feeds"><b>45</b> feeds found.</div>

serialize()

Serializes a set of input elements into a string of data. This will serialize all given elements.

A serialization similar to the form submit of a browser is provided by the Form Plugin. It also takes multiple-selects into account, while this method recognizes only a single option.

Return value: String
Example:

 $("input[@type=text]").serialize();

 <input type='text' name='name' value='John'/>
 <input type='text' name='location' value='Boston'/>