Submit API Basic Example
Here, we’re going to create a very basic example with the submit API. Let’s say that you’ve created a Wufoo account with a username of “examples”, and your form that you’d like to build an API off of is named “Contact Me” that looks exactly like this. The only problem is you want that form to seamlessly appear on your site without the use of an iframe.
Before you get started, you may also want to check out a great introduction to our API that was created by one of our users.
Download the Files
Oftentimes, the easiest way to learn something is by taking a look at the actual working code, installing it on your servers, and playing around. So here are the exact files needed in order to get this basic api example working.
Building the Form
For this basic example, I’m going to copy the exact form markup that Wufoo made for the Contact Me form except at the top of the page, I’m going to include a processing page.
require_once($root.'/api/example/example-process.php');
As I’ll explain later, you’ll need to create a processing page that takes the form’s field values after it’s submitted, communicates with the Wufoo servers to submit the form data, and handles any errors or confirmation messages after the data is processed by Wufoo.
The rest of the form can look identical to the code found on the actual Wufoo form, and you’re also welcome to copy and paste the javascript and CSS files into your own webserver.
<div class="info">
<h2>Contact Me</h2>
<p>Feel Free to Contact Me Anytime</p>
</div>
<ul id="formFields">
<li class="" id="fo19li0">
<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 class="" id="fo19li1">
<label class="desc" for="Field1">Message</label>
<div>
<textarea id="Field1"
name="Field1"
rows="10" cols="50"
class="field textarea medium"></textarea>
</div>
</li>
<li class="buttons">
<input id="saveForm" class="btTxt" type="submit" value="Submit" />
</li>
</ul>
</form></code>
The Processing Page
The processing page that was included at the top of our form is where we’re going to run all of the logic. This page will gather up all of the form values into a request to send to Wufoo, communicate with Wufoo’s servers regarding the status of the submission, and hold the functions that display error messages to the user.
At the very top of the processing page is a little snip of code that basically says don’t even try and talk to Wufoo’s servers until your user presses the submit button.
if (count($_POST) > 0) {
$fieldErrors = initAPI($root);
}
Building the Request
Once the user submits the form, the processing page will need to build a request, or basically turn the Form’s data into a nice and neat array before sending it to Wufoo for processing. This request will need three items: the Wufoo form name, your API Key, and the form’s fields.
To find these three items log into Wufoo, head to the ‘Account’ section, and click on API. There you will find the API Key that looks something like this
XXXX-SV3T-5LWF-ZZZZ
And the form names and their fields looking like the table below:
11. contact-me
| API ID | Field Title |
| 0 | Email Address |
| 1 | Message |
To build the request, start by creating a new array and setting the API key and form name as the first two parameters.
$wufoo_query_vals = array(
'w_api_key' => '0000-0000-0000-0000',
'w_form' => 'Contact-Me',
Next, we’ll need to set the form fields to the correct values. As we can see in the table above, this form has two fields named 0 and 1. In the same array, wufoo_query_vals, set the form fields 0 and 1 to the information filled out by the user.
'0' => $_POST['Field0'],
'1' => $_POST['Field1']
);
After the array is built, you’ll want to build a POST string by looping through the array and url encoding the values.
foreach($wufoo_query_vals as $key => $value) {
$request .= $key.'='.urlencode($value).'&';
}
Finally, we don’t want the request to contain an ampersand at the end, so we just trim it off using a basic trim function.
$request = rtrim($request, ‘&’);
Sending the Request to Wufoo
Now that the $request variable contains all the information that you want to send to Wufoo, let’s take a look at how to send the data to Wufoo’s servers.
Wufoo needs you to send the complete URL to your form, so take the form , and substitute the subdomain examples with your Wufoo username. For this demo, the username is examples.
http://examples.wufoo.com/api/insert/
Now that we know the url to send the request to, we’ll use PHP’s libcurl library to send the data to Wufoo. To learn more about CURL for your programming language and how to set it up, head to http://curl.haxx.se/.
$ch = curl_init("http://examples.wufoo.com/api/insert/");
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($ch);
curl_close ($ch);
What that snip of code first does is send the $request variable containing all of he form’s information to Wufoo. Then, after Wufoo checks to see if the data is valid, it will send a JSON string back to your servers. In this example, we create a variable, $response, to hold this JSON string.
Handling the Response
Now that the data has been sent to Wufoo, validated, and a JSON string returned to us regarding the validity of the submission, we’ll want to find out what exactly was returned.
Since PHP and other server-side programming languages cannot easily decipher a JSON string, it first needs to be converted into an object that can be easily manipulated. The class we used for converting the JSON string can be downloaded, and if you would like to learn more about the JSON, head on over to the section on the Submit API Response
require_once($root.'/classes/json.php');
Once the class is included, we run a function that converts the JSON string into an object array that PHP can manipulate more easily.
//$wufoo_response is an object array of the JSON string values
$wufoo_response = getFormJson($response);
//$response is the variable returned by the CURL functions containing the JSON formatted string
function getFormJson($response) {
$json = new Services_JSON();
$input = $response;
$g_form = $json->decode($input);
return $g_form;
}
The variable $wufoo_response is an object containing all of the information that was in the JSON string, $response.
Handling the Response
O.k., so now that we have submitted the data to Wufoo’s servers, received a JSON string containing the success or failure of the submission, and turned that string into an object that PHP can manipulate, let’s take a look at how we’d deal with a successful and unsuccessful submission.
Successful Submission
The object $wufoo_response contains all of the information concerning our submission to Wufoo. The variable wufoo_submit[0] is the first item in the $wufoo_response array, and the variable ‘success’ will hold either a value of “true” or “false” depending if the submission was successful or not.
function success($wufoo_response){
$success = $wufoo_response->wufoo_submit[0]->success;
if ($success == "true") echo "Successful Submission!";
else return false;
}
If “submit” comes back true then your submission was successful. You can now redirect the user, display a thank you message, or do whatever you want after a successful submission.
** Note that you’ll always be dealing with wufoo_submit[0] since Wufoo will never return more than one JSON string at a time.
Validation Errors
If the success function returns false, then there was something wrong with the data being submitted. To find out what the field errors were during the submission, we’ll look at the variable, “field_errors”, which is an array containing all of the validation errors that occurred. In the example, we run a function called buildErrors that loops through the array of field_errors and builds new associative array in the form of fieldId -> error message.
function buildErrors($wufoo_response){
$errorCount = count($wufoo_response->wufoo_submit[0]->field_errors);
$fieldErrors = array();
$response = $wufoo_response->wufoo_submit[0]->field_errors;
for($i = 0; $i<$errorCount; $i++ ){
$fieldErrors[$response[$i]->field_id] = $response[$i]->error_message;
}
return $fieldErrors;
}
Now that we have an array containing all of the field id’s and the errors associated with those id’s we can inform the user that there are errors present and which fields the errors belong to.
