fuzzyness

Hosting Wufoo forms on your own server

20·Apr·07

Yesterday I posted about Wufoo, a very cool form-building web application (see that post). As I mentioned, I find more and more to love about the service each day.

The only small stickler for me as a web designer is that I’d like the forms to be hosted on my own server, rather than on Wufoo’s. Currently you can either have the whole form page hosted with them, or you can cheat a little and use an iframe to call in the form itself into a page on your own site. I understand why this has to be so, and it’s not too much of a problem.

However, as iframes invalidate a strict DOCOTYPE, and they’re not great for accessibility, I decided to once and for all get to grips with using the Wufoo API to host my Wufoo forms on my own server. I can still have the forms processed, checked and validated by Wufoo, with access to all the beautiful reporting, but I also keep it in the family (so to speak).

There’s a great example of how to get started with this on the Wufoo site, but I wanted to give a bit of a step-by-step walkthrough for the more, erm, programatically-challenged – you know who you are. More than anything, I want to have a record of the process that works for me. My instructions are far less generally useful than the run-through from the Wufoo guys, but they’ve helped me get the job done.

Although it takes a mere minute to get a form up and running with the standard iframe option provided by Wufoo, it still only takes a paltry 5 minutes using the API, which is peanuts! Onwards…

Building the form itself

1. Log into Wufoo and create a form. Build a simple contact form for now, 2 fields only. Here's one I prepared earlier in approximately 30 seconds (hosted on the Wufoo servers at this stage). Save your form.

2. On the next screen, choose the 'Integrate it into a website or blog post' option. Then choose 'Integrated Form Code' from the 3 options presented to the right.

   Copy and paste the URL provided within the provided code (in my example case here it was http://definition.wufoo.com/embed/contact-form/) and visit that URL in a browser. 'View source' - this contains the standard HTML form code we'll need. Easy. Nice one Wufoo!

Preparing the basic page

1. Copy and paste the form code itself only. Everything between the opening and closing form tags, basically. Here's one I made earlier, pasted directly from Wufoo's admin interface:

   <form id="form3" class="wufoo" method="post" action="" 
   enctype="multipart/form-data">
   
   <ul id="formFields">
   
     <li>
     <label class="desc" for="field0">Email address</label>
       <div>
         <input id="field0" name="field0" class="field text medium" 
          type="text" maxlength="255" value=""/> 
       </div>
     </li>
   
     <li>
       <p class="instruct">Here's a helper instruction for the user.</p>
       <label class="desc" for="field1">Message</label>
         <div>
           <textarea id="field1" name="field1" rows="10" cols="50" 
            class="field textarea small">
           </textarea>
         </div>
        </li>
   
   </ul>
   
   <div class="buttons">
     <input id="submit" name="submit" class="button" 
     type="submit" value="Submit" />
   </div>
   
   </form>

2. Visit the stylesheet reference given in the form source code (e.g. /css/public.css). Copy and paste the CSS styles, and pop them in a new CSS file. Put this on your server and link to it, just as you link to your other stylesheet(s). The provided CSS is very well documented and commented, as a great base for further alterations.

3. Note there are some extra IE7 styles at /css/global/ie7.css which again you may want to have as default anyway. This how I'd link 'em up on my server:

   <!--[if IE 7]>
   <link rel="stylesheet" href="/css/browsers/ie7-form.css" type="text/css" />
   <![endif]-->

4. Copy the code at /scripts/public/dynamic.js and again link to this as normal:

   <script type="text/javascript" src="/js/dynamic.js"></script>

5. Save this lot as, say, contact-form.php. You could call it whatever you like.

You now have a beautifully styled form page on your own server. Let's hook it up!

Preparing the form processing files

We'll come back to our actual form page in a minute. First, let's prepare the 2 files we'll need to handle processing the form data and get that out of the way. I've created a forms folder on my server just to hold these general form processing files. Note: the actual form page itself can go anywhere, just nice to have the 2 files responsible for processing in one convenient place.

1. Go to http://wufoo.com/docs/api/submit/ and grab the latest example files from the Download The Files link. It'll be easier to work from these than to start from scratch.

2. Rename example-process.php to form-process.php. No reason really, just that we're going to use this file regularly, so might as well give it a more permanent name!

3. Log-in to your Wufoo account. Click the Account tab and then click the API Information button (like this one):

   

4. Take note of your API Key number, plus have a look at the table underneath it. Mine looks like this:

   

   You'll need to know the corresponding ID number for each of your fields, plus the form name (in this case, contact-form)

5. Open form-process.php in your favourite text editor. Whizz down to line 9, and alter the following code for your server:

   require_once($root.'/forms/json.php');

   If you remember, I've created a forms folder in my site starter files, in which json.php can sit.

6. Scroll down now to line 22 and see the following function:

   function setPostParams(){
   	$wufoo_query_vals = array(
       	'w_api_key' => '0000-0000-0000-0000',
       	'w_form' => 'name-of-form',
   
   		'0' => $_POST['Field0'],
   		'1' => $_POST['Field1']
   	);
   	return $wufoo_query_vals;
   }

   Replace the API Key with your own, and change the form name to yours (see the table given on your own Wufoo API page, like the example in the image). Then add the ID numbers for your form fields, as appropriate. In our example, there are only 2 form fields, but you might have many, many in your own form. Just add them on as required, e.g.

   '0' => $_POST['Field0'],
   		'1' => $_POST['Field1']
   		'2' => $_POST['Field2']
   		'3' => $_POST['Field3']
   		'4' => $_POST['Field4']
   

   Although this definitely covers requirements for most fields, you'll definitely want to check out the definitive list in the API docs here to see how to format trickier fields like date and phone, if you've included them in your form.

7. Last thing in this file: go down to line 46 and alter the URL to reflect your own username. For me, it's definition so I have mine like this:

   $ch = curl_init("http://definition.wufoo.com/api/insert/");  

8. For our simple purposes we're now done with form-process.php and don't need to alter anything in json.php, so go ahead and upload these 2 files to your server. As mentioned, I've put mine in a folder called forms just to keep things tidy.

9. Finally, we haven't touched example.php in the examples folder at all, but you can just trash that file. Really. It's not that it's not useful, but I've already plundered the juicy bits for you (coming next… the excitement!) and we don't need the distraction of the contents of the rest of the file.

Plugging it all together

Now we need to get it all working together.

1. Open up your prepared contact-form.php file. Pop the following code into the very top, before the DOCTYPE:

   <?php
     require_once($root.'/forms/form-process.php'); 
   ?>

   Obviously, alter the path accordingly for where you've put it on your server.

2. Now we need to finally put some small bits of PHP in place, in each form field, to allow validation and error-reporting to function correctly. Here's a sample bit of code, which is the entirety of my first form field:

   <li <? echo addErrors('field0', $fieldErrors, 'class') ?>>
     <label class="desc" for="field0">Email Address</label>
   
       <div>
         <input id="Field0" name="field0" class="field text medium" type="text" maxlength="255" value="" /> 
       </div>
   <? echo addErrors('field0', $fieldErrors, 'message')?>
   </li>

   You'll notice there's merely the addition of 2 bits of PHP: one within the opening list tag itself, and one directly before the closing list tag. The field number (in this example, field0) corresponds with the field number assigned by Wufoo for this particular field (see your API page under your Account tab). Just go through each form field and add those bits of PHP in, changing the field number to the one assigned to it by Wufoo.

3. Finally, to get the error-reporting actually reporting back to the user, simply add the following bit of code to just inside the opening of the unordered list (but before the very first list item):

   <?php       // general 'you've got errors' message
   	if (sizeof($fieldErrors) >0) echo "<li id=\"errorLi\">
   	<h3 id=\"errorMsgLbl\">There was a problem with your submission.</h3>
   	<p id=\"errorMsg\">Errors have been <strong>highlighted</strong> below.</p>
   	</li>"
   ?>

Now just upload your new contact-form.php page, visit in a browser, and see it in action. Here's the one I made - lovely isn't it?

That about wraps it up

That's the very, very basics of what Wufoo has to offer. Don't forget, you could just as easily create a form in Wufoo and have it called into your page via an iframe, in seconds. We've only used the API so that we can host the form on our own server, and avoid an iframe altogether. We still get Wufoo's marvellous form processing, validation and error checking, and can give clients access to a wonderful reporting system too.

Steamlining the process

Obviously, once you've been through this process once, you might like to standardise it to save time for future forms. I'd keep basic copies of the CSS, PHP and javascript files in a standard place, keeping all paths and references as constant as possible. Then really the only work will be to create the form, grab the code, paste it into place, make a few quick parameter or value changes, and that should be it.

Taking this further

Obviously the API is a powerful thing, and I've merely scraped the very surface of what you could achieve. Our example is very simple - you'll definitely want to be checking out the rest of the instructions given in the Wufoo Submit API docs, as well as the info in the general API docs too. Hats off to the Wufoo guys for creating a fantastic programming interface to an already brilliant product.

Back to home page »