Description: Load data from the server using a HTTP POST request.
- version added: 1.0jQuery.post( url, [ data ], [ success(data, textStatus, jqXHR) ], [ dataType ] )
urlA string containing the URL to which the request is sent.
dataA map or string that is sent to the server with the request.
success(data, textStatus, jqXHR)A callback function that is executed if the request succeeds.
dataTypeThe type of data expected from the server. Default: Intelligent Guess (xml, json, script, or html).
This is a shorthand Ajax function, which is equivalent to:
$.ajax({ type: 'POST', url: url, data: data, success: success dataType: dataType });The success callback function is passed the returned data, which will be an XML root element or a text string depending on the MIME type of the response. It is also passed the text status of the response.
As of jQuery 1.5, the success callback function is also passed a "jqXHR" object (in jQuery 1.4, it was passed the XMLHttpRequest object).
Most implementations will specify a success handler:
$.post('ajax/test.html', function(data) { $('.result').html(data); });This example fetches the requested HTML snippet and inserts it on the page.
Pages fetched with POST are never cached, so the cache and ifModified options in jQuery.ajaxSetup() have no effect on these requests.
The jqXHR ObjectAs of jQuery 1.5, all of jQuery's Ajax methods return a superset of the XMLHTTPRequest object. This jQuery XHR object, or "jqXHR," returned by $.post() implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see Deferred object for more information). For convenience and consistency with the callback names used by $.ajax(), it provides .error(), .success(), and .complete() methods. These methods take a function argument that is called when the request terminates, and the function receives the same arguments as the correspondingly-named $.ajax() callback.
The Promise interface in jQuery 1.5 also allows jQuery's Ajax methods, including $.post(), to chain multiple .success(), .complete(), and .error() callbacks on a single request, and even to assign these callbacks after the request may have completed. If the request is already complete, the callback is fired immediately.
// Assign handlers immediately after making the request, // and remember the jqxhr object for this request var jqxhr = $.post("example.php", function() { alert("success"); }) .success(function() { alert("second success"); }) .error(function() { alert("error"); }) .complete(function() { alert("complete"); }); // perform other work here ... // Set another completion function for the request above jqxhr.complete(function(){ alert("second complete"); });- Due to browser security restrictions, most "Ajax" requests are subject to the same origin policy; the request can not successfully retrieve data from a different domain, subdomain, or protocol.
- If a request with jQuery.post() returns an error code, it will fail silently unless the script has also called the global .ajaxError() method or. As of jQuery 1.5, the .error() method of the jqXHR object returned by jQuery.post() is also available for error handling.
