Chris Barr

Ajax Forms in Expression Engine with FreeForm

Friday, March 21, 2008

Introduction

Something I've been wanting for a while was a way to integrate a contact form in Expression Engine with some nice AJAX effects from my favorite Javascript library, Mootools. I've not been able to find anything out there that does exactly what I want, so I've made my own. This does require the FreeForm Module for Expression Engine from Solspace as well as Mootools 1.11.

View a Demo

Download It! (v. 1.1.1)

Click the jump for more information on how to set this up...

Preparation

First, you obviously need to have a basic understanding of Expression Engine, and of course install it on your site.

Next, you’ll need to install the FreeForm Module into Expression Engine.

Now, lets make a custom build of Mootools 1.11, so click the link to go to the download page and here’s the minimum requirements for Mootools.  Obviously you can add more to the file if your site has other needs.

• Core
• Class
  - Class
  - Class.Extras
• Native
  - Array
  - String
  - Function
  - Number
  - Element
• Element
  - Element.Event
  - Element.Filters
  - Element.Selectors
  - Element.Form
• Window
  - Window.DomReady
  - Window.Size
• Effects
  - Fx.Base
  - Fx.CSS
  - Fx.Styles
  - Fx.Elements
  - Fx.Slide
• Remote
  - XHR
  - AJAX

Templates

Now we need to create some templates in Expression Engine.  First create a web page template and it’s contents will be “success” and nothing else.  This is just a single word.  This is the template we will tell FreeForm to go to when the form has been filled out correctly.  Of course the end user will never see this, we just use AJAX to check if we get this word back, and if we do then the form was submitted successfully.

Now create another web site template, and this one will be what the user sees and actually contains the form.  Use the example in the download if you need help with what to put in here.  Just be sure to link you both mootools and the form script, and obviously use the FreeForm tags here to create the form. If you need help with using FreeForm I suggest that you read the documentation or ask on the Solspace Forum.  I do not provide support for Expression Engine or FreeForm.

Customization

Now that everything is inside Expression Engine, you’ll probably need to tweak the form itself and my script to fit your needs.  First, lets look at the HTML we need to have for the form.  Lets say we want to add a new field called “Location” to the default form that I include in the example.  Each field needs a label associated with it, and that label must have a unique ID assigned to it.  Here’s an example:

<label for="location" id="location_label">Your Location:</label>
<input type="text" class="formField" id="location" name="location"  size="40" />

That’s easy enough.  Don’t forget to add the field into the FreeForm module, otherwise you’ll get errors about the field not existing in FreeForm.

Now if we want to make this field a required field, we need to add it to the script. This as easy as adding an array, so if I were to add the location field to the example file in the download/demo it would look like this:

var inputs = [
 ["Name","name_label", false],
 ["Location","location_label", false],
 ["Email","email_label", true],
 ["Message","message_label", false],
 ["captcha","captcha_label", false]
];

Now there’s three values to each array.

The first value is the Label the field has inside the FreeForm module.  This is case sensitive!  You want to have this exact because if the field is not filled out it will give an error message of “The following field is required: Location” and the script just checks the text in this line for the word “Location”.

The second value is the ID of the label for that field.  We need this so that we can highlight it when there’s a problem.  Again, this must be exact, and it must be unique.

That last value is a boolean, meaning it can be set to either true or false.  If it’s set to true, then the script will perform an extra check on this field to see if it is correct.  For example, FreeForm will check email addresses in the email field to make sure they are valid.  This gets triggered it you forget to add the .com on the end, or leave out the @ symbol, etc.  FreeForm is what performs the check on the field, we just need to match that up with the script so that if there’s a problem other than it being blank, it gets flagged with an error.

Just keep in mind you only need to add fields to this variable if they are required fields!  If they are optional fields, you don’t need to do anything since FreeForm doesn’t care if you fill it out or not.

There are a few other options you can play with, but they are all pretty self-explanatory and are described well in the comments of the script.

CAPTCHA fields

If you want to use captcha in your field, you’ll need to add the captcha field to the variable.  Keep the first value as “captcha” since this word is used in FreeForm’s error message.  There are some EE tags surrounding the part of the code that checks the captcha form, which are there to make sure that captcha is currently turned on before checking it.  Be sure to leave these tags, otherwise when a user is logged in and they try to use the form, it will try and check for the captcha form which doesn’t exist (only if you hide captcha from logged in users).

CSS Styles

I’ve included two CSS files in the download.  One is just to get the design of the page set, and the other one is all the required CSS styles for elements used by the script, and this is the main one you need to be working with.

One of the biggest problems I’m having right now is that when the AJAX request is received and placed into the hidden div, it loads that entire HTML page, along with it’s CSS.  The CSS from this page can and will overtake CSS styles that you have written for a brief period.  Once the data has been grabbed from that page, it is discarded.

I’ve only experienced the CSS takeover in Firefox and Opera, and it is very brief.  The best way to prevent this from happening is to add an !important; to most of your CSS styles.  If it’s set to !important; then this should have a higher priority than whatever other CSS is loaded in.

It’s not a glamourous way to fix this, but it’s all I know to do at the moment.  If anyone has any better suggestions, I’d be happy to hear them.

Compatability

This was tested as working using FreeForm 2.6.4 and Expression Engine 1.6.3.  Basically this is just some javascript running, so if FreeForm works, this should work.

I’ve personally tested this as 100% working in the following browsers:

• Firefox 2.0.0.12 (Mac, Windows, and Linux)
• Safari 3.1 (Mac and Windows)
• Opera 9.26 (Mac and Windows)
• Camino 1.5.5
• Internet Explorer 6
• Internet Explorer 7
• Konqueror 3.5.8 (no transparency in overlay)

(Mac Browser run under Leopard 10.5.2, Windows Browsers under XP SP2, and Linux Browsers under Ubuntu 7.10 [GNOME 2.20.1])

Licensing & Final Notes

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.  You may use this for commercial purposes as long as you make the source code avalible and do not remove the comments that link back to my site.  You may modify this script in any way you need.

If you have any questions or suggestions, or if you use this, I’d love to know about it - so leave me a comment!