Basic Query with a JSON Return
Introduction
The Wufoo Query API enables us to pull data from any Wufoo account given an API key and a form URL. The data is then returned in one of two formats: JSON and XML. For this tutorial, we will walk through the steps needed to query data from Wufoo, and then display the data onto a web page.
The Files
The files for this tutorial are available for download:
Additionally, a few extra steps must be confirmed to ensure that the example works properly on your setup:
- The server is capable of running PHP 5 scripts.
- The server has CURL installed.
- The example uses JSON-PHP. The PHP files is included in the zip, but it is safe to go to the official website and download the latest copy.
See it in Action
There is a public Wufoo API account named “Fishbowl” to be used for developer testing. This example pulls records from one of the forms in that account, and displays them on a datagrid.
View a live preview of this tutorial in action.
Getting Started
To get started with the files, just copy the zip folder, named JSON, to a directory on your web server. After that, open up index.html and locate the first line.
$path_to_folder = $_SERVER['DOCUMENT_ROOT'].'/api/query/examples/json/';
Change this line to reflect the path that you placed the files in. Once the files are setup, the example should work. The next step is to understand the logic. Four main actions are taking place in the entire process — after this brief overview, we will go over each in depth.
Build the query: Construct the URL that will be sent to the Wufoo servers. The URL specifies what type of data you would like to recieve.
Send the query: Once we have a query, we can send it off to Wufoo using CURL. A response containing the data will then be returned in JSON format.
Convert the JSON: Given a response, we can convert it to a JSON object using the JSON-PHP library.
Display the results: Finally, loop through the data and display it on the web page.
Build the Query
The Query API has a set of paramteres that can be used to specify the dataset we would like returned. These parameters are built into a URL, as shown in the function buildQuery().
function buildQuery() {
// Set the Wufoo Query POST parameters
$wufoo_query_vals = array(
'w_api_key' => 'YOUR API KEY HERE',
'w_form' => 'what-is-your-name',
'w_format' => 'json'
);
// Generate the POST string
foreach($wufoo_query_vals as $key => $value) {
$request .= $key.'='.urlencode($value).'&';
}
// Chop of the trailing ampersand
$request = rtrim($request, '&');
return $request;
}
In this example, the 3 parameters used are w_api_key, w_form, and w_format. Note that it is important to replace hthe w_api_key with that of your own Wufoo account. The w_form value signals which form to pull data from, and the w_format value tells Wufoo to return it in a JSON format. If you were to leave out w_format, the default response would be in an XML format.
Once the buildQuery() function is run, a string will be returned in a field=value&field2=value2 format.
Send the Query
Once the query is built, the sendQuery() function takes name/value pair formatted string as a parameter. Then, using CURL, it sends that query off to the Wufoo servers. On line 22 of process.php, the URL is established:
$ch = curl_init("http://fishbowl.wufoo.com/api/query/");
It is important to change the username to your own. In this case, fishbowl will become your Wufoo username. Once the URL is properly configured, the rest of the function will execute as expected.
function sendQuery($request) {
$ch = curl_init("http://fishbowl.wufoo.com/api/query/");
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($ch);
curl_close ($ch);
return $response;
}
The key part of this function is the $response variable. When the CURL request is finished, that variable will contain a string in JSON format of your results. The variable is then returned at the end of the function.
Convert the JSON
Now that we have a string returned from the Wufoo server in JSON format, we can convert the string to an actual JSON object. convertJSON() will do that for us.
function convertJson($response) {
$json = new Services_JSON();
$ret = $json->decode($response);
return $ret;
}
Using the decode() function in the JSON-PHP library, we can convert the string into an object. All this means is that you can use the syntax oh a PHP object to access the data. For example, the following code now works:
// Success: true or false
$wuquery->success;
// Total record count
/$wuquery->total_records;
Display the Results
With the $wuquery object in place, the last step is to loop through the data contained in the object, and draw it on an HTML table. This is divided into three sections: the HTML, looping through the headers, and looping through the data. Let’s look at the HTML first.
<?php if($wuquery->success) { ?>
<div class="tableBottom clearfix">
<div class="left">Viewing entries <strong>1</strong> to <strong><?php echo $wuquery->total_records; ?></strong>.</div>
</div>
<div class="dg">
<table id="entries" class="entries" cellspacing="1">
<thead>
<tr>
<?php echo drawQueryHeaders($wuquery->query_headers); ?>
</tr>
</thead>
<tbody>
<?php echo drawQueryData($wuquery->query_records); ?>
</tbody>
</table>
</div>
Notice that we check to make sure the query was a success. Afterwards, the total record count is displayed, as well as a call to drawQueryHeaders() and drawQueryData(). drawQueryHeaders() will draw the table head, which contains the titles of the fields in your form.
function drawQueryHeaders($headers) {
$count = count($headers);
$ret = '';
for($i = 0; $i < $count; $i++) {
$ret .= '<td>'.$headers[$i]->title.'</td>';
}
return $ret;
}
This function is quite simple. A count of the headers is taken. Then the array is looped through up until the count, with each item being displayed inside of <td> tags. drawQueryData() works almost identically.
function drawQueryData($data) {
$count = count($data);
$ret = '';
for($i = 0; $i < $count; $i++) {
$ret .= '<tr>';
foreach($data[$i] as $key => $value) {
$ret .= '<td>'.$value.'</td>';
}
$ret .= '</tr>';
}
return $ret;
}
The main difference with this function is that there are multiple rows of data, so we have to place each row within a <tr> tag before we begin looping through each individual item.
Bugs and Questions
Should you run into any problems with this example, or the Query API in general, please place your questions in the forum or contact support@wufoo.com. Additionally, if you expect to heavily use this API (more than 5000 requests per day) please contact us before hand, so that we can go over details.
