jQuery Form Plugin

The jQuery Form Plugin allows you to easily and unobtrusively upgrade HTML forms to use AJAX

View on GitHub

Examples

ajaxForm

The following code controls the HTML form beneath it. It uses ajaxForm to bind the form and demonstrates how to use pre- and post-submit callbacks.

// prepare the form when the DOM is ready
$(document).ready(function() {
  var options = {
    target:        '#output1',   // target element(s) to be updated with server response
    beforeSubmit:  showRequest,  // pre-submit callback
    success:       showResponse  // post-submit callback

    // other available options:
    //url:       url         // override for form's 'action' attribute
    //type:      type        // 'get' or 'post', override for form's 'method' attribute
    //dataType:  null        // 'xml', 'script', or 'json' (expected server response type)
    //clearForm: true        // clear all form fields after successful submit
    //resetForm: true        // reset the form after successful submit

    // $.ajax options can be used here too, for example:
    //timeout:   3000
  };

  // bind form using 'ajaxForm'
  $('#myForm1').ajaxForm(options);
});

// pre-submit callback
function showRequest(formData, jqForm, options) {
  // formData is an array; here we use $.param to convert it to a string to display it
  // but the form plugin does this for you automatically when it submits the data
  var queryString = $.param(formData);

  // jqForm is a jQuery object encapsulating the form element. To access the
  // DOM element for the form do this:
  // var formElement = jqForm[0];

  alert('About to submit: \n\n' + queryString);

  // here we could return false to prevent the form from being submitted;
  // returning anything other than false will allow the form submit to continue
  return true;
}

// post-submit callback
function showResponse(responseText, statusText, xhr, $form)  {
  // for normal html responses, the first argument to the success callback
  // is the XMLHttpRequest object's responseText property

  // if the ajaxForm method was passed an Options Object with the dataType
  // property set to 'xml' then the first argument to the success callback
  // is the XMLHttpRequest object's responseXML property

  // if the ajaxForm method was passed an Options Object with the dataType
  // property set to 'json' then the first argument to the success callback
  // is the json data object returned by the server

  alert('status: ' + statusText + '\n\nresponseText: \n' + responseText +
    '\n\nThe output div should have already been updated with the responseText.');
}
Name:
Password:
Multiple:
Single:
Single2:
Check:
Radio:
Text:

Output Div (#output1):

AJAX response will replace this content.

ajaxSubmit

The following code controls the HTML form beneath it. It uses ajaxSubmit to submit the form.

// prepare the form when the DOM is ready
$(document).ready(function() {
    var options = {
        target:        '#output2',   // target element(s) to be updated with server response
        beforeSubmit:  showRequest,  // pre-submit callback
        success:       showResponse  // post-submit callback

        // other available options:
        //url:       url         // override for form's 'action' attribute
        //type:      type        // 'get' or 'post', override for form's 'method' attribute
        //dataType:  null        // 'xml', 'script', or 'json' (expected server response type)
        //clearForm: true        // clear all form fields after successful submit
        //resetForm: true        // reset the form after successful submit

        // $.ajax options can be used here too, for example:
        //timeout:   3000
    };

    // bind to the form's submit event
    $('#myForm2').submit(function() {
        // inside event callbacks 'this' is the DOM element so we first
        // wrap it in a jQuery object and then invoke ajaxSubmit
        $(this).ajaxSubmit(options);

        // !!! Important !!!
        // always return false to prevent standard browser submit and page navigation
        return false;
    });
});

// pre-submit callback
function showRequest(formData, jqForm, options) {
    // formData is an array; here we use $.param to convert it to a string to display it
    // but the form plugin does this for you automatically when it submits the data
    var queryString = $.param(formData);

    // jqForm is a jQuery object encapsulating the form element. To access the
    // DOM element for the form do this:
    // var formElement = jqForm[0];

    alert('About to submit: \n\n' + queryString);

    // here we could return false to prevent the form from being submitted;
    // returning anything other than false will allow the form submit to continue
    return true;
}

// post-submit callback
function showResponse(responseText, statusText, xhr, $form)  {
    // for normal html responses, the first argument to the success callback
    // is the XMLHttpRequest object's responseText property

    // if the ajaxSubmit method was passed an Options Object with the dataType
    // property set to 'xml' then the first argument to the success callback
    // is the XMLHttpRequest object's responseXML property

    // if the ajaxSubmit method was passed an Options Object with the dataType
    // property set to 'json' then the first argument to the success callback
    // is the json data object returned by the server

    alert('status: ' + statusText + '\n\nresponseText: \n' + responseText +
        '\n\nThe output div should have already been updated with the responseText.');
}
Name:
Password:
Multiple:
Single:
Single2:
Check:
Radio:
Text:

Output Div (#output2):

AJAX response will replace this content.

Validation

This section gives several examples of how form data can be validated before it is sent to the server. The secret is in the beforeSubmit option. If this pre-submit callback returns false, the submit process is aborted.

The following login form is used for each of the examples that follow. Each example will validate that both the username and password fields have been filled in by the user.

Form Markup:

  <form id="validationForm" action="http://malsup.com/jquery/form/dummy.php" method="post">
    Username: <input type="text" name="username">
    Password: <input type="password" name="password">
    <input type="submit" value="Submit">
  </form>

First, we initialize the form and give it a beforeSubmit callback function - this is the validation function.

// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#myForm2').ajaxForm( { beforeSubmit: validate } );
});

Validate Using the formData Argument

Username: Password: 
function validate(formData, jqForm, options) {
  // formData is an array of objects representing the name and value of each field
  // that will be sent to the server;  it takes the following form:
  //
  // [
  //     { name:  username, value: valueOfUsernameInput },
  //     { name:  password, value: valueOfPasswordInput }
  // ]
  //
  // To validate, we can examine the contents of this array to see if the
  // username and password fields have values. If either value evaluates
  // to false then we return false from this method.

  for (var i=0; i < formData.length; i++) {
    if (!formData[i].value) {
      alert('Please enter a value for both Username and Password');
      return false;
    }
  }
  alert('Both fields contain values.');
}

Validate Using the jqForm Argument

Username: Password: 
function validate(formData, jqForm, options) {
    // jqForm is a jQuery object which wraps the form DOM element
    //
    // To validate, we can access the DOM elements directly and return true
    // only if the values of both the username and password fields evaluate
    // to true

    var form = jqForm[0];
    if (!form.username.value || !form.password.value) {
        alert('Please enter a value for both Username and Password');
        return false;
    }
    alert('Both fields contain values.');
}

Validate Using the fieldValue Method

Username: Password: 
function validate(formData, jqForm, options) {
    // fieldValue is a Form Plugin method that can be invoked to find the
    // current value of a field
    //
    // To validate, we can capture the values of both the username and password
    // fields and return true only if both evaluate to true

    var usernameValue = $('input[name=username]').fieldValue();
    var passwordValue = $('input[name=password]').fieldValue();

    // usernameValue and passwordValue are arrays but we can do simple
    // "not" tests to see if the arrays are empty
    if (!usernameValue[0] || !passwordValue[0]) {
        alert('Please enter a value for both Username and Password');
        return false;
    }
    alert('Both fields contain values.');
}

Note

You can find jQuery plugins that deal specifically with field validation on the jQuery Plugins Page.

JSON

This page shows how to handle JSON data returned from the server. The form below submits a message to the server and the server echos it back in JSON format.

Form markup:

<form id="jsonForm" action="http://malsup.com/jquery/form/json-echo.php" method="post">
    Message: <input type="text" name="message" value="Hello JSON">
    <input type="submit" value="Echo as JSON">
</form>
Message:

Server code in json-echo.php:

<?php  echo '{ "message": "' . $_POST['message'] . '" }';  ?>

JavaScript:

// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#jsonForm').ajaxForm({
        // dataType identifies the expected content type of the server response
        dataType:  'json',

        // success identifies the function to invoke when the server response
        // has been received
        success:   processJson
    });
});

Callback function

function processJson(data) {
    // 'data' is the json object returned from the server
    alert(data.message);
}

XML

This page shows how to handle XML data returned from the server. The form below submits a message to the server and the server echos it back in XML format.

Form markup:

<form id="xmlForm" action="http://malsup.com/jquery/form/xml-echo.php" method="post">
  Message: <input type="text" name="message" value="Hello XML">
  <input type="submit" value="Echo as XML">
</form>
Message:

Server code in xml-echo.php:

<?php
// !!! IMPORTANT !!! - the server must set the content type to XML
header('Content-type: text/xml');
echo '<root><message>' . $_POST['message'] . '</message></root>';
?>

JavaScript:

// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#xmlForm').ajaxForm({
        // dataType identifies the expected content type of the server response
        dataType:  'xml',

        // success identifies the function to invoke when the server response
        // has been received
        success:   processXml
    });
});

Callback function

function processXml(responseXML) {
    // 'responseXML' is the XML document returned by the server; we use
    // jQuery to extract the content of the message node from the XML doc
    var message = $('message', responseXML).text();
    alert(message);
}

HTML

This page shows how to handle HTML data returned from the server. The form below submits a message to the server and the server echos it back in an HTML div. The response is added to this page in the htmlExampleTarget div below.

Form markup:

<form id="htmlForm" action="http://malsup.com/jquery/form/html-echo.php" method="post">
    Message: <input type="text" name="message" value="Hello HTML">
    <input type="submit" value="Echo as HTML">
</form>
Message:

Server code in html-echo.php:

<?php
echo '<div style="background-color:#ffa; padding:20px">' . $_POST['message'] . '</div>';
?>

JavaScript:

// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#htmlForm').ajaxForm({
        // target identifies the element(s) to update with the server response
        target: '#htmlExampleTarget',

        // success identifies the function to invoke when the server response
        // has been received; here we apply a fade-in effect to the new content
        success: function() {
            $('#htmlExampleTarget').fadeIn('slow');
        }
    });
});

htmlExampleTarget (output will be added below):

File Upload

This page demonstrates the Form Plugin’s file upload capabilities. There is no special coding required to handle file uploads. File input elements are automatically detected and processed for you.

Browsers that support the XMLHttpRequest Level 2 will be able to upload files seamlessly and even get progress updates as the upload proceeds. For older browsers, a fallback technology is used which involves iframes since it is not possible to upload files using the level 1 implmenentation of the XMLHttpRequest object. This is a common fallback technique, but it has inherent limitations. The iframe element is used as the target of the form’s submit operation which means that the server response is written to the iframe. This is fine if the response type is HTML or XML, but doesn’t work as well if the response type is script or JSON, both of which often contain characters that need to be repesented using entity references when found in HTML markup.

To account for the challenges of script and JSON responses when using the iframe mode, the Form Plugin allows these responses to be embedded in a textarea element and it is recommended that you do so for these response types when used in conjuction with file uploads and older browsers.

It is important to note that even when the dataType option is set to ‘script’, and the server is actually responding with some javascript to a multipart form submission, the response’s Content-Type header should be forced to text/html, otherwise Internet Explorer will prompt the user to download a “file”.

Also note that if there is no file input in the form then the request uses normal XHR to submit the form (not an iframe). This puts the burden on your server code to know when to use a textarea and when not to. If you like, you can use the iframe option of the plugin to force it to always use an iframe mode and then your server can always embed the response in a textarea. But the recommended solution is to test for the ‘X-Requested-With’ request header. If the value of that header is ‘XMLHttpRequest’ then you know that the form was posted via ajax.

The following PHP snippet shows how you can be sure to return content successfully:

<?php
$xhr = $_SERVER['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest';
if (!$xhr) 
  echo '<textarea>';
?>

// main content of response here
        
<?php
if (!$xhr)  
  echo '</textarea>';
?>

The form below provides an input element of type “file” along with a select element to specify the dataType of the response. The form is submitted to files.php which uses the dataType to determine what type of response to return.

File: Return Type:

Examples that show how to display upload progress: