# jQuery website jQuery documentation

## Ajax

### loadIfModified(String url, Map params, Function callback) : jQuery

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

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

#### Example

##### Before

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

##### Code

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

##### Result

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

### load(String url, Object params, Function callback) : jQuery

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

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.

#### Examples

##### Before

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

##### Code

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

##### Result

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

Same as above, but with an additional parameter and a callback that is executed when the data was loaded.

##### Code

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

### serialize() : String

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.

#### Example

Serialize a selection of input elements to a string

##### Before

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

##### Code

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

### evalScripts() : jQuery

Evaluate all script tags inside this jQuery. If they have a src attribute, the script is loaded, otherwise it's content is evaluated.

### ajaxStart(Function callback) : jQuery

callback | Function | The function to execute.

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

#### Example

Show a loading message whenever an AJAX request starts (and none is already active).

##### Code

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

### ajaxStop(Function callback) : jQuery

callback | Function | The function to execute.

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

#### Example

Hide a loading message after all the AJAX requests have stopped.

##### Code

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

### ajaxComplete(Function callback) : jQuery

callback | Function | The function to execute.

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.

#### Example

Show a message when an AJAX request completes.

##### Code

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

### ajaxSuccess(Function callback) : jQuery

callback | Function | The function to execute.

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.

#### Example

Show a message when an AJAX request completes successfully.

##### Code

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

### ajaxError(Function callback) : jQuery

callback | Function | The function to execute.

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.

#### Example

Show a message when an AJAX request fails.

##### Code

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

### ajaxSend(Function callback) : jQuery

callback | Function | The function to execute.

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

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

#### Example

Show a message before an AJAX request is sent.

##### Code

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

### $.get(String url, Map params, Function callback) : XMLHttpRequest

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.

Load a remote page using an HTTP GET request.

#### Examples

##### Code

    $.get("test.cgi");

##### Code

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

##### Code

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

##### Code

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

### $.getIfModified(String url, Map params, Function callback) : XMLHttpRequest

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.

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

#### Examples

##### Code

    $.getIfModified("test.html");

##### Code

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

##### Code

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

##### Code

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

### $.getScript(String url, Function callback) : XMLHttpRequest

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

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.

#### Examples

##### Code

    $.getScript("test.js");

##### Code

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

### $.getJSON(String url, Map params, Function callback) : XMLHttpRequest

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.

Load JSON data using an HTTP GET request.

#### Examples

##### Code

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

##### Code

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

### $.post(String url, Map params, Function callback) : XMLHttpRequest

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.

Load a remote page using an HTTP POST request.

#### Examples

##### Code

    $.post("test.cgi");

##### Code

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

##### Code

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

##### Code

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

### $.ajaxTimeout(Number time) : undefined

time | Number | How long before an AJAX request times out.

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.

#### Example

Make all AJAX requests timeout after 5 seconds.

##### Code

    $.ajaxTimeout( 5000 );

### $.ajaxSetup(Map settings) : undefined

settings | Map | Key/value pairs to use for all AJAX requests

Setup global settings for AJAX requests.

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

#### Example

Sets the defaults for AJAX requests to the url "/xmlhttp/", disables global handlers and uses POST instead of GET. The following AJAX requests then sends some data without having to set anything else.

##### Code

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

### $.ajax(Map properties) : XMLHttpRequest

properties | Map | Key/value pairs to initialize the request with.

Load a remote page using an HTTP request.

This is jQuery's low-level AJAX implementation. See $.get, $.post etc. for higher-level abstractions.

$.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: Make sure the server sends the right mimetype (eg. xml as "text/xml"). Sending the wrong mimetype will get you into serious trouble that jQuery can't solve.

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.

#### Examples

Load and execute a JavaScript file.

##### Code

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

Save some data to the server and notify the user once its complete.

##### Code

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

Loads data synchronously. Blocks the browser while the requests is active. It is better to block user interaction with others means when synchronization is necessary, instead to block the complete browser.

##### Code

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

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.

##### Code

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