control-freak-ide/Control-Freak-Documentation/jQuery/docs/entries/jQuery.post.json

{"name":"jQuery.post","type":"method","title":"jQuery.post()","deprecated":null,"removed":null,"desc":"Load data from the server using a HTTP POST request.","categories":["ajax/shorthand-methods","version/1.0","version/1.5"],"entries":[{"return":"jqXHR","signatures":{"added":"1.0","argument":[{"desc":"A string containing the URL to which the request is sent.","name":"url","type":"String"},{"type":[{"name":"PlainObject"},{"name":"String"}],"desc":"A plain object or string that is sent to the server with the request.","name":"data","optional":"true"},{"desc":"A callback function that is executed if the request succeeds. Required if <code>dataType</code> is provided, but can be <code>null</code> in that case.","name":"success(data, textStatus, jqXHR)","optional":"true","type":"Function"},{"desc":"The type of data expected from the server. Default: Intelligent Guess (xml, json, script, text, html).","name":"dataType","optional":"true","type":"String"}]},"examples":[{"desc":"Request the test.php page, but ignore the return results.","code":"\n$.post( \"test.php\" );\n"},{"desc":"Request the test.php page and send some additional data along (while still ignoring the return results).","code":"\n$.post( \"test.php\", { name: \"John\", time: \"2pm\" } );\n"},{"desc":"Pass arrays of data to the server (while still ignoring the return results).","code":"\n$.post( \"test.php\", { 'choices[]': [ \"Jon\", \"Susan\" ] } );\n"},{"desc":"Send form data using ajax requests","code":"\n$.post( \"test.php\", $( \"#testform\" ).serialize() );\n"},{"desc":"Alert the results from requesting test.php (HTML or XML, depending on what was returned).","code":"\n$.post( \"test.php\", function( data ) {\n  alert( \"Data Loaded: \" + data );\n});\n"},{"desc":"Alert the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).","code":"\n$.post( \"test.php\", { name: \"John\", time: \"2pm\" })\n  .done(function( data ) {\n    alert( \"Data Loaded: \" + data );\n  });\n"},{"desc":"Post to the test.php page and get content which has been returned in json format (<?php echo json_encode(array(\"name\"=>\"John\",\"time\"=>\"2pm\")); ?>).","code":"\n$.post( \"test.php\", { func: \"getNameAndTime\" }, function( data ) {\n  console.log( data.name ); // John\n  console.log( data.time ); // 2pm\n}, \"json\");\n"},{"desc":"Post a form using ajax and put results in a div","code":"\n// Attach a submit handler to the form\n$( \"#searchForm\" ).submit(function( event ) {\n\n  // Stop form from submitting normally\n  event.preventDefault();\n\n  // Get some values from elements on the page:\n  var $form = $( this ),\n    term = $form.find( \"input[name='s']\" ).val(),\n    url = $form.attr( \"action\" );\n\n  // Send the data using post\n  var posting = $.post( url, { s: term } );\n\n  // Put the results in a div\n  posting.done(function( data ) {\n    var content = $( data ).find( \"#content\" );\n    $( \"#result\" ).empty().append( content );\n  });\n});\n","html":"\n<form action=\"/\" id=\"searchForm\">\n  <input type=\"text\" name=\"s\" placeholder=\"Search...\">\n  <input type=\"submit\" value=\"Search\">\n</form>\n<!-- the result of the search will be rendered inside this div -->\n<div id=\"result\"></div>\n"}],"longdesc":"\n    <p>This is a shorthand Ajax function, which is equivalent to:</p>\n    <pre><code>\n$.ajax({\n  type: \"POST\",\n  url: url,\n  data: data,\n  success: success,\n  dataType: dataType\n});\n    </code></pre>\n    <p>The <code>success</code> 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.</p>\n    <p><strong>As of jQuery 1.5</strong>, the <code>success</code> callback function is also passed a <a href=\"#jqxhr-object\">\"jqXHR\" object</a> (in <strong>jQuery 1.4</strong>, it was passed the <code>XMLHttpRequest</code> object).</p>\n    <p>Most implementations will specify a success handler:</p>\n    <pre><code>\n$.post( \"ajax/test.html\", function( data ) {\n  $( \".result\" ).html( data );\n});\n    </code></pre>\n    <p>This example fetches the requested HTML snippet and inserts it on the page.</p>\n    <p>Pages fetched with <code>POST</code> are never cached, so the <code>cache</code> and <code>ifModified</code> options in <code><a href=\"/jQuery.ajaxSetup/\">jQuery.ajaxSetup()</a></code> have no effect on these requests.</p>\n    <h4 id=\"jqxhr-object\">The jqXHR Object</h4>\n    <p><strong>As of jQuery 1.5</strong>, all of jQuery's Ajax methods return  a superset of the <code>XMLHTTPRequest</code> object. This jQuery XHR object, or \"jqXHR,\" returned by <code>$.get()</code> implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see <a href=\"/category/deferred-object/\">Deferred object</a> for more information). The <code>jqXHR.done()</code> (for success), <code>jqXHR.fail()</code> (for error), and <code>jqXHR.always()</code> (for completion, whether success or error) methods take a function argument that is called when the request terminates. For information about the arguments this function receives, see the <a href=\"/jQuery.ajax/#jqXHR\">jqXHR Object</a> section of the $.ajax() documentation.</p>\n        <p>The Promise interface also allows jQuery's Ajax methods, including <code>$.get()</code>, to chain multiple <code>.done()</code>, <code>.fail()</code>, and <code>.always()</code> 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.</p>\n    <pre><code>\n// Assign handlers immediately after making the request,\n// and remember the jqxhr object for this request\nvar jqxhr = $.post( \"example.php\", function() {\n  alert( \"success\" );\n})\n  .done(function() {\n    alert( \"second success\" );\n  })\n  .fail(function() {\n    alert( \"error\" );\n  })\n  .always(function() {\n    alert( \"finished\" );\n});\n\n// Perform other work here ...\n\n// Set another completion function for the request above\njqxhr.always(function() {\n  alert( \"second finished\" );\n});\n    </code></pre>\n\n    <h4>Deprecation Notice</h4>\n    <p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods introduced in jQuery 1.5 are <strong>deprecated as of jQuery 1.8</strong>. To prepare your code for their eventual removal, use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>\n  "}]}