Submitting Forms with Ajax

When you submit a form, the next page displayed is normally the "success" or "thanks" page. This is the easiest approach, and usually it is a perfectly reasonable approach. This is what you will get by default when you set up a form as described in Creating Forms for User Submissions.

There are times, however, when you want to submit the form but stay on the same page. For example, you might have a small contact form in the sidebar of a page, and want to continue to display that page after the form is submitted.

Setting Up a Form for Ajax Submission

You can do this by using an Ajax form submission. The form is submitted using JavaScript, rather than the normal form submit action, and the confirmation or error message is displayed by inserting the content using JavaScript.

There's a few steps to converting a form submission to use an Ajax submit:

1. Start with the standard form code the Webvanta system provides for your custom item type.
2. Wrap the form in a div with an ID, so you can hide the form after it is submitted.
3. Add empty divs for the success and error messages, so the JavaScript code can put content there when the form is submited.
4. Add a hidden field to the form that tells the Webvanta system that you are doing an Ajax submit.
5. Add some jQuery code that replaces the normal submit with an Ajax submit and processes the response.

Note: because of the JavaScript security model, you cannot reliably perform Ajax form submits to a domain other than the one that is hosting the form. So you cannot use this technique with forms that submit to another service, such as an email marketing provider.

HTML Changes

Here's an example that illustrates the first three items above:

<div id="form_success"></div>
<div id="form_errors"></div>
<div id="form_wrapper">
  <form ...>
  (normal form code goes here)
  <input type='hidden' name='contact[ajax]' value='json' />
  </form>
</div>

The only change we've made to the form itself is to add a hidden form element with the name contact[ajax] whose value is set to json. This tells the Webvanta system that you want to perform an Ajax submit, and that you'd like the results delivered in json format. Make sure to adjust the name attribute's prefix of contact to be what-ever name prefix your form actually uses.

Submitting with jQuery

Now you just need a little JavaScript to handle the form processing:

<script type="text/javascript">
$(document).ready(function(){
    $("form").submit(function() {
      $("input[type='submit']").attr("disabled","disabled");
      $.post($("form").attr("action"),
        $("form").serialize(),
        function(data, textStatus){
            if (data.status == 'ok') {
                $("#form_wrapper").hide();
                $("#form_success").text("Thank you for your submission");
            } else {                  
                $("input[type='submit']").removeAttr("disabled");
                if (data.errors.length > 0) {
                  $("#form_errors").html("<p>The following errors occurred:</p><ul>" +
                      $.each(data.errors, function(){
                         "<li>" + this + "</li>";
                      }) + "</ul>" );
                } else {
                    $("#form_errors").text("Something went wrong:" + textStatus);
                }
            }
        },
        'json');
      return false;
  })
});
</script>

Here's a summary of what this code is doing:

1. The submit function provided here runs when the submit button is clicked.
2. It disables the submit button, so you only get one submit.
3. The jQuery post function performs the ajax submit. The parameters are:
   • The URL of the page to which the form data should be posted. We use a little jQuery code to grab this from the action attribute of the form.
   • The serialized form data.
   • A function that is executed to process the results returned by the Ajax post.
   • The format type of the returned data, which for the Webvanta system is json.
4. The function returns "false" so the normal HTTP post will not occur.

Processing the Response

Most of the complexity is in the function that processes the response—in particular, in dealing with any errors. Webvanta returns two objects:

• The data object, which contains:
  • A text field (data.status) that will contain the string "ok" if all went well.
  • An array of strings (data.errors) that explain any validation errors.
• A status string (textStatus) that explains what went wrong, if there was some sort of communication or server error.

Now that we understand these two objects, the actions performed by the result-processing function are clear. If the status is "ok", meaning that the form was successfully submitted:

1. Hide the form.
2. Display a "thank you" message in the "form_success" div.

You should be using JavaScript validation on the form, so any validation errors will be caught before the form is submitted. But if something slips through and the server rejects the post, you need to be prepared.

If the submit fails, things are a little more complicated. The code:

1. Re-enables the submit button, since the submit process did not complete.
2. If there are any validation error messages (in the data.errors array), display them. In the example here, we've formatted them in an unordered list.
3. If there are no validation error messages (data.errors is empty), then there must have been some sort of communication or server error, so display the textStatus string.

Using With Your Own Forms

You can easily adapt any of your own forms to use this Ajax submit approach. Just remember to follow each of the steps outlined in the beginning of this article, and add the JavaScript code above to the head section of your page.

If you have only one form on the page, and you name your divs as in our example, you should be able to use the JavaScript code we've shown here without modification. If you have multiple forms, change each instance of $("form") to $("#form_id"), where form_id is the ID of the form you want to work with.