jQuery website jQuery documentation

Ajax

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

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

Example

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

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

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

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

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

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

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

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

$("#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

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

$("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

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

Example

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

ajaxStop(Function callback) : jQuery

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

Example

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

ajaxComplete(Function callback) : jQuery

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

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

ajaxSuccess(Function callback) : jQuery

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

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

ajaxError(Function callback) : jQuery

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

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

ajaxSend(Function callback) : jQuery

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

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

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

Load a remote page using an HTTP GET request.

Examples

$.get("test.cgi");

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

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

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

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

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

Examples

$.getIfModified("test.html");

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

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

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

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

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

$.getScript("test.js");

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

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

Load JSON data using an HTTP GET request.

Examples

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

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

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

Load a remote page using an HTTP POST request.

Examples

$.post("test.cgi");

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

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

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

$.ajaxTimeout(Number time) : undefined

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

$.ajaxTimeout( 5000 );

$.ajaxSetup(Map settings) : undefined

Setup global settings for AJAX requests.

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

Example

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

$.ajax(Map properties) : XMLHttpRequest

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

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

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

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

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