Post to Free Form w/ Ajax Validation

October 30th, 2010 | Filed in: Third party add-ons | Comment on This Post

We use the excellent free EE module from solspace, Free Form on many of our Expression Engine websites. The plugin is easy to manage, can be styled with CSS easily, and functions beautifully. We wanted to add a layer of javascript to our form post to allow users to send POST information to our Free Forms unobtrusively. By using the jquery form plugin we post our data via jQuery's built in ajax functionality and allow users to send information without a page refresh and with live validation.

Graceful Degradation
Free Form allows for users with javascript disabled to still communicate their POST data. This is important because communications sent to your website should be as accessible as possible. The added layer of javascript we are including to make our form submission experience smoother is purely aesthetic. The all php back-up that Free Form provides is imperative.

Setting Up Your Template
We have included a standard Free Form set up inside of an Expression Engine template below. Note that we have included an extra <span> inside of our form <label> tags. We will use these empty <span> tags to inject our failed validation messages with jQuery:

{exp:freeform:form form:id="contactform" notify="eric@mediasuture.com" required="user_name|user_email|user_comments" template="contact_form" collection="Demo Form"}
<fieldset>
<label for="user_name">*Name <span class="requiredname"></span></label>
<input type="text" id="contact_name" name="user_name" />
</fieldset>

<fieldset>
<label for="user_email">*Email <span class="requiredemail"></span></label>
<input type="text" id="contact_email" name="user_email" />
</fieldset>

<fieldset>
<label for="user_comments">*Message <span class="requiredmsg"></span></label>
<textarea rows="5" id="contact_comments" cols="" name="user_comments"></textarea>
</fieldset>

<input type="submit" value="submit" size="20" name="submit" class="sendbutton" />
{/exp:freeform:form}

Before We Add Interactivity
Let's review what elements are already in place in our Free Form mark-up. We want to make certain that our Free Form is set up correctly before we add our javascript because if users have javascript disabled, we want to make certain our Free Form is transmitting the correct information. We open our Free Form using the plugin's tag. We also set our form ID (this is mostly for our CSS styling purposes), and the we establish the email address that will be receiving information posted (via the free form notify declaration). Lastly, we define which fields are required. In our example all fields are required.

{exp:freeform:form form:id="contactform" notify="email@yourwebsite.com" required="user_name|user_email|user_comments" template="contact_form" collection="Contact Form"}

When we write our form input elements, we use the <label> tag to identify each field uniquely. As mentioned earlier, we include a <span> tag with a CSS class applied. In the next step we will include some custom jquery to inject text into this empty span tag. This is to alert users that the filed is required. The text will appear inside this <span> only if the form is submitted with missing input information (or in the instance of the email field, if it fails our simple email reg check):

  <fieldset>
  <label for="user_name">*Name <span class="requiredname"></span></label>
 <input type="text" id="contact_name" name="contact_name" />
  </fieldset>

The rest of the fields are similar to the code snippet above, so lets move on.

Introducing Interactivity
Now that we have correctly created our Free Form entry and our physical form mark-up is written in the way we want it, we are going to introduce a layer of Javascript. The Javascript layer will offer us the ability to submit the form without refreshing the web page (via ajax) but more importantly, it will provide us with some live validation.

Resources
To make our form work the way we intend, we will need a couple of libraries. First and foremost, jquery. IMPORTANT! at the time of this writing, jquery1.4.3 is behaving oddly and unbinding our form id on submit on some browsers, so until I can find a reason for this, please use jquery.1.4.2. The second library required is the jquery.form plugin. It is available freely at the Github repository: here. Once those two scripts are installed in the head of your document (remember that the jquery1.4.2 library comes before the jquery.form plugin) we are read to include our custom jquery validation script:

Validation Script

$(document).ready(function(){

$("#contactform").ajaxForm( { beforeSubmit: validate } );

function validate(formData, jqForm) {

//Define our form
var form = jqForm[0];

// Set error status to false initally
var hasError = false;

// Define our email registration check
var emailReg = /^([\w-\.]+@([\w-]+\.)+[\w-]{2,4})?$/;

//Set our email input field from our form equal to a new variable emailVal
var emailVal = $("#contact_email").val();

// If our emailVal variable is empty we perform some actions
if(emailVal == '') {
$(".requiredemail").html("Please Enter An Email");
$("#contact_email").css({ backgroundColor: "#B80000", color: "#FFFFFF" });
hasError = true;

// if our email registration check fails we perform some actions
} else if(!emailReg.test(emailVal)) {
$(".requiredemail").html("Enter a valid email");
$("#contact_email").css({ backgroundColor: "#b80000", color: "#FFFFFF" });
hasError = true;

//If the email is NOT empty and passes our registration check we set the field color to white and the text to grey
} else if (emailVal != '' || emailReg.test(emailVal)) {$("#contact_email").css({ backgroundColor: "#FFFFFF" , color: "#545454" });
$(".requiredemail").html("");
}

//Set our name input field from our form equal to a new variable called nameVal
var nameVal = $("#contact_name").val();

// If our name input field is empty we perform some actions
if(nameVal == '') {
$(".requiredname").html("Please provide a name");
$("#contact_name").css({ backgroundColor: "#b80000", color: "#FFFFFF" });
hasError = true;

//If the name is NOT empty we set the field color to white and the text to grey
} else if(nameVal != '') {$("#contact_name").css({ backgroundColor: "#FFFFFF" , color: "#545454" });
$(".requiredname").html("");
}

//We create a new variable called commentsVal and set it equal to our comments input field from our form
var commentsVal = $("#contact_comments").val();

//If our comments field is empty we perform some actions
if(commentsVal == '') {
$(".requiredmsg").html("Enter your message");
$("#contact_comments").css({ backgroundColor: "#b80000" , color: "#FFFFFF" });
hasError = true;

//If our comments field is NOT empty we make certain the style of our field is white and the text is grey
} else if(commentsVal != '') {$("#contact_comments").css({ backgroundColor: "#FFFFFF" , color: "#545454" });
$(".requiredmsg").html("");
}

// If NO errors are detected in our form we fade out our form entirely and include a message after it
if(hasError == false) {
$("#contactform").fadeOut("slow", function() {
$("#contactform").after('<h2><strong>Thank You</strong></h2><p>Your message has been sent</p>');
});
}}

});

I have commented out the script heavily for you so that you can see how the selectors we added to the span tags in our form now act as wrappers for our validation error text. We are also changing the color of our input fields to red when there is an error, and switching the text color to white so that it stands out. We've also applied a simple fade function with jQuery to remove the form with some animation, and then include some "Thank You" text alerting the user they have submitted their form. All of the data contained within your form is processed via the jquery.form plugin, serialized and sent to your Free Form.

Source Files
We have included an Expression Engine template with all of the parameters outlined in this demo for your convenience (as well as some inline styles to make the form demo easier to execute). Also included in the archive are the 3 Javascript files needed to power this tutorial: jquery.1.4.2 library, jquery.form plugin, and our custom validation.js script.