# jQuery.post()

## jQuery.post ( url, data, success(data, textStatus, jqXHR), dataType ) Returns: jqXHR version added: 1.0

- url
  Type: String
  A string containing the URL to which the request is sent.

- data
  Type:
  A plain object or string that is sent to the server with the request.

- success(data, textStatus, jqXHR)
  Type: Function
  A callback function that is executed if the request succeeds. Required if dataType is provided, but can be null in that case.

- dataType
  Type: String
  The type of data expected from the server. Default: Intelligent Guess (xml, json, script, text, html).

Description: Load data from the server using a HTTP POST request.

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 Object

As 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 `$.get()` implements the Promise interface, giving it all the properties, methods, and behavior of a Promise (see Deferred object for more information). The `jqXHR.done()` (for success), `jqXHR.fail()` (for error), and `jqXHR.always()` (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 jqXHR Object section of the $.ajax() documentation.

The Promise interface also allows jQuery's Ajax methods, including `$.get()`, to chain multiple `.done()`, `.fail()`, and `.always()` 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" );
    })
      .done(function() {
        alert( "second success" );
      })
      .fail(function() {
        alert( "error" );
      })
      .always(function() {
        alert( "finished" );
    });

    // Perform other work here ...

    // Set another completion function for the request above
    jqxhr.always(function() {
      alert( "second finished" );
    });

#### Deprecation Notice

The `jqXHR.success()`, `jqXHR.error()`, and `jqXHR.complete()` callback methods introduced in jQuery 1.5 are deprecated as of jQuery 1.8. To prepare your code for their eventual removal, use `jqXHR.done()`, `jqXHR.fail()`, and `jqXHR.always()` instead.

## Examples:

#### Example: Request the test.php page, but ignore the return results.

    $.post( "test.php" );

#### Example: Request the test.php page and send some additional data along (while still ignoring the return results).

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

#### Example: Pass arrays of data to the server (while still ignoring the return results).

    $.post( "test.php", { 'choices[]': [ "Jon", "Susan" ] } );

#### Example: Send form data using ajax requests

    $.post( "test.php", $( "#testform" ).serialize() );

#### Example: Alert the results from requesting test.php (HTML or XML, depending on what was returned).

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

#### Example: Alert the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).

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

#### Example: 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")); ?>).

    $.post( "test.php", { func: "getNameAndTime" }, function( data ) {
      console.log( data.name ); // John
      console.log( data.time ); // 2pm
    }, "json");

#### Example: Post a form using ajax and put results in a div

    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>css demo</title>

      <script src="//code.jquery.com/jquery-1.10.2.js"></script>
    </head>
    <body>

    <form action="/" id="searchForm">
      <input type="text" name="s" placeholder="Search...">
      <input type="submit" value="Search">
    </form>
    <!-- the result of the search will be rendered inside this div -->
    <div id="result"></div>

    <script>

    // Attach a submit handler to the form
    $( "#searchForm" ).submit(function( event ) {

      // Stop form from submitting normally
      event.preventDefault();

      // Get some values from elements on the page:
      var $form = $( this ),
        term = $form.find( "input[name='s']" ).val(),
        url = $form.attr( "action" );

      // Send the data using post
      var posting = $.post( url, { s: term } );

      // Put the results in a div
      posting.done(function( data ) {
        var content = $( data ).find( "#content" );
        $( "#result" ).empty().append( content );
      });
    });

    </script>

    </body>
    </html>

#### Demo: