JQuery notes / AJAX notes
| Related to web development, hosting, and such: (See also the webdev category)
Dynamic server stuff:
|This article/section is a stub — probably a pile of half-sorted notes, is not well-checked so may have incorrect bits. (Feel free to ignore, fix, or tell me)|
...Back when XHR was called AJAX...
There are a number of ways to AJAX, mostly variations that can be handy for specific uses.
Most basic functions take a URL, an optional parameter map, and an optional callback funtion. Note this is a success callback only(verify) - but note you can regularly use a global error/complete handler instead of one for each request.
Various simple ways
If you are fetching things to be put into the DOM, you can use:
- .load( url[,data[,callback]] ) - Do fetch, parse as HTML, enter data into DOM
- .loadIfModified( url[,data[,callback]] )
In general, the ...IfModified variants do a conditional fetch based on Last-Modified headers
If you want to handle the data yourself, you want one of the following helper functions. They return a XMLHttpRequest object, but you can usually ignore it and do your work in the callback, which gives you the fetched data.
- $.get( url[,data[,callback]] ), a basic GET
- $.getIfModified( url[,data[,callback]] )
- $.post( url[,data[,callback]] ), a basic POST
And special cases:
- $.getJSON( url[,data[,callback]] ), in which the callback data is an object evaluated from the fetched JSON
- $.getScript( url[,callback] ), load and execute a script:
The hard way
If you want more control, you can use the function the above are based on: $.ajax(). It takes only a map, in which you can set:
- url: the URL
- type: 'GET' or 'POST' (default: GET)
- data: more parameters, processed into the URL unless you use processdata:true
- beforeSend: passes the XMLHttpRequest, allowing you to use setRequestHeader()
- error: error handler
- success: success handler that passes the fetched data - often simpler than:
- complete: called on any result (success, error, abort()). Passes in the XMLHttpRequest and a string describing the type of result, one of 'success', 'error', 'timeout', 'notmodified', or 'parsererror'.
- global: whether or not to trigger the global handlers for this request (default is true)
Some handle-things-for-me options:
- processData: true is default. False leaves data as request data in POSTs
- ifModified: true or false (default: false)
- timeout: timeout for this specific request. null/0 disables timeout (default), otherwise a number in milliseconds.
- dataType: one of
- 'xml' - return XML structure (Note that Content-Type headers also help - for example, xml types will trigger 'xml' treatment)
- 'html' - return plain text (script tags are apparently evaluated)
- 'script' (eval()uated in global context)
- 'json' (returns eval() of data)
- 'jsonp' (verify)
- async: defaults to true, asynchronous requests (...happen in the background). If set to false, makes request synchronous (blocking).
- You can manually call abort() on a XMLHttpRequest
- a timeout or abort() will set readyState=0 and trigger the error() and complete() callbacks (verify)
Global setup, global callbacks
You can set some global settings to apply to all requests via
- $.ajaxSetup(), sets things that apply to all ajax calls. You can pass any option you would otherwise pass to $.ajax()
You can also add global callback handlers like:
- ajaxSend ( func ) (think beforeSend)
- ajaxError( func )
- ajaxComplete ( func )
- ajaxSuccess ( func )
- ajaxStart ( func ) and ajaxStop ( func ) are events reflecting whether there are or aren't any current requests. Useful for things like 'loading...' messages.
Related: Form encoding
You may also be interested in serialize() and plugins like jQuery Form Plugin, which allow you to select form elements and serialize them into a query string, allowing you to imitate a form submit via an AJAX call.