Today’s guest post is from Noah Coffey, a web developer/designer and creator of Tweetbrite.

One of my favorite uses for FormSpring is throwing together a registration form for a conference or event.  As the popularity of Twitter continues to explode, I’ve noticed more event registration forms asking for attendee’s Twitter user names. If you are organizing and event, wouldn’t it be nice if you could automatically tweet every time someone registers for your event?

A site that provides such a service has just integrated with FormSpring. Tweetbrite now allows you to connect your FormSpring account to your Twitter account. Every time someone uses your Formspring event registration form, Tweetbrite can automatically tweet through your selected Twitter account. For example, “@johnsmith just registered for MBO 2009.”

To get started, just create a new FormSpring API key from your FormSpring account (tutorial). Then, head over to Tweetbrite.com, create a free account, and click the big “Get started” link once you log-in. A simple setup wizard will guide you through the steps to link your FormSpring account, your Twitter account and create your mashup. Another great feature provided through the use of the FormSpring API key is that you never have to reveal your FormSpring user name or password.

For those interested in details of the integration, the FormSpring API was very intuitive and easy to use. Once Tweetbrite is granted access to a user’s FormSpring account and a mashup has been created, selected FormSpring forms are checked regularly for new attendee data. Based on which form fields the user selected, Tweetbrite stores the new attendee’s first and last name and their Twitter user name. Another process tweets the new attendees in the format specified by the user and marks the attendee as having been tweeted (to prevent duplicate tweeting). I wish I could go into more detail about the integration, but the FormSpring API is really straightforward and the documentation is excellent.

Noah Coffey is a developer trapped inside a web designer. While spending his days enjoying the challenges of web and email design, his true passion lies in side projects developing unique and creative web apps in the social media space. He is also the co-founder of Blog Indiana, an annual blogging and social media conference located in Indianapolis, IN. Noah lives and works in Indianapolis, is married and a proud new fatherRecent Posts:

• FormSpring Launches New Data/Report Features
• How To Embed Google Analytics Into Your Form
• New Multilingual Support Text On Forms

Other Related Posts

• The Twall of Fame
• Don’t Forget The Emergency Contact Form
• More Pre-Built Web Forms

Now that FormSpring has an API, the fun part begins. How do we use it?

One of the things I like to do is monitor my forms to see if any new data has been collected. I’d kind of like something that just hangs around in the background, watching the form, and if someone submits a form, it lets me know.

Widgets are a perfect application for this, and I put together both a Yahoo Widget as well as a Mac OS X Dashboard widget that does just what I need.

If you’re interested in how the widgets were built so you can customize them on your own, keep reading and I’ll give a quick overview.

The Yahoo Widget

Yahoo Widgets are, essentially, a combination of XML and Javascript. You bundle these files together, and they make up your widget (Full Yahoo Widget documentation can be found here).

The file FormSpring.kon contains the XML that defines the widget. I have 2 frames, or views, one to display the form information and the other to allow you to enter your API key. In this file, I also define a timer:

<timer>
    <name>timer</name>
    <interval>30</interval>
    <ticking>true</ticking>
    <onTimerFired>fetchFormInformation();</onTimerFired>
</timer>

I use this so that every 30 minutes, the widget calls the fetchFormInformation() function and, as you can guess from the name, fetches the form information. I’ve defined that function in the main.js file, and it looks something like this:

function fetchFormInformation() {

	// get the Form ID and the API Key
	var apiKey = preferences.apiKey.value;
	var formID = preferences.selectedFormID.value;

	// build url for the call
	var location = 'https://www.formspring.com/api/form?api_key=' + apiKey + '&id=' + formID + '&type=json';

	// get that information asynchronously
	var url = new URL();
	url.location = location;
	url.fetchAsync(fetchFormInformationHandler);
}

Here, I’m doing a couple of things. First, I get the API Key and the selected Form ID from the preferences (these are stored elsewhere in the widget). I then build the URL for the call, and then grab the information. You’ll notice I use type=json in the URL so that I get back JSON data.

Yahoo Widgets have a very nice URL object that does most of the heavy lifting for me, and I create a new URL object to do so. As you can see, I’m fetching this information asynchronously, and I define a handler function (fetchFormInformationHandler) that gets called once the information has been retrieved. Here is an excerpt:

function fetchFormInformationHandler(url) {

	var data = url.responseData.parseJSON();

	var formData = data.response;

	// populate the form with the new values
	formName.data = formData.name;
	formSubmissionTotal.data = formData.submissions;
	formViews.data = formData.views;
}

Since I’ve asked the API for JSON data (using type=json in the URL), the first thing I need to do is convert it to a format I can use. In the widget, I’ve included a file called json.js which has a nice function that does this for me. So, I get the response text from the URL object, then immediately convert that from JSON into a Javascript object.

From there, it’s trivial to update the various interface elements with the data I just fetched.

The Dashboard Widget

For the Mac OS X Dashboard widget, I did essentially the same thing. In this case, I needed to use a different method to parse the JSON data. For example, in the file FormSpring.js, I have a similar method to the Yahoo Widget called fetchFormInformation(). Unlike the Yahoo Widget, though, I don’t need a handler, this one is all self contained:

function fetchFormInformation() {

	// get the Form ID and the API Key
	var apiKey = $('apiKey').value;
	var formID = $('formSelect').options[$('formSelect').selectedIndex].value;

	var url = 'https://www.formspring.com/api/form';

	// get the information for this form, then change the front of the widget
	new Ajax.Request(url,
	  {
		method:'get',
		parameters: {api_key: apiKey, id: formID, type: 'json'},
		onSuccess: function(transport) {

			// get the JSON data array
			data = transport.responseText.evalJSON();

			// use the response data to populate the widget
			formData = data.response;

			$('formResponses').innerHTML = formData.submissions;
			$('formName').innerHTML = formData.name;

			if (formData.views)
				$('formViews').innerHTML = formData.views;
		},
		onFailure: function(){ alert('Something went wrong...') }
	  });
}

Here, I’m using an Ajax request method to get the form information. Once I have it, I do the same thing as with the Yahoo Widget: I parse the JSON data (with evalJSON()), then update the interface with the information.

Once you get the hang of it, it’s pretty easy. Yahoo and Apple both have excellent documentation and plenty of examples. In addition, you can download the source code (Yahoo Widget source here and Dashboard widget here) of these widgets, crack them open, and try your hand at creating your own.

Have fun, and feel free to add any comments or questions below.Recent Posts:

• FormSpring Launches New Data/Report Features
• Make Your Event Registration Form Tweet
• How To Embed Google Analytics Into Your Form

Other Related Posts

• Make Your Event Registration Form Tweet

This is the last of three Google mashup articles this week for programmers who want to explore the new FormSpring API. If you haven’t seen them yet, take a look at the Google Maps mashup and the Google Spreadsheets mashup.

This one will take data submitted on a FormSpring form and create new events in Google Calendar. This might be helpful if you want to use your calendar to track registrations for a workshop series, or if your customers are submitting requests to schedule service. Once integration is setup, new events can appear on the calendar soon after a form is submitted. You can also extend the example so events aren’t created as soon as the form is submitted — you can create a hidden date/time field on your form that is for administrative use only, and have events created only when that field has been set.

Feel free to download the example PHP code and follow along. The example code uses the Zend Framework PHP Client Library to access the Google Calendar API. You will need to download the Zend framework in order to use this.

To get started you’ll need to have a form with at least one date field that contains the event start time. You’ll also need to create a FormSpring API key that has data access to your form.

In this example we have a date field labeled “Start Time”, another labeled “End Time” and a text field labeled “Event Title”. We’ll map these to the appropriate values when creating a calendar event. More information about all the event attributes can be found in the Google Calendar API documentation.

The script starts by getting a list of fields on the form, looking for the fields we need to create the event, then mapping the field id to the event attribute.

$field_labels = array(
    'title' => 'Event Title',
    'start' => 'Start Time',
    'end'   => 'End Time',
);
 
// Get information on the FormSpring form
$form = FormSpring::request($api_key, 'form', array( 'id' => $form_id ));
 
// Get form field ids for the title, start and end fields
$fields = array();
foreach ($form['fields'] as $field) {
    foreach ($field_labels as $key => $label) {
        if ($field['label'] == $label) {
            $fields[$field['id']] = $key;
        }
    }
}

Now we can start searching submitted data and creating events. As with yesterday’s example, the assumption is made that this script will be scheduled to run in cron on a regular basis. We’ll need some mechanism to make sure that we don’t create new events for old submissions. For the sake of simplicity, in the example we do that by downloading the prior day’s worth of submissions and assume that the script will only run once a day. The min_time and max_time parameters (which search against the submission date and time for each record) can easily be changed to do this on an hourly basis, or we can locally store the unique id of the last submission so the script isn’t tied to the date and time it’s run.

When downloading the submitted data only a pre-defined number of results (25 by default) are returned at each time, and we’ll need to make multiple requests to the API to download each “page” of results.

// Loop through each page, making one query per page of data
$pages = 1;
while ($parameters['page'] <= $pages) {
 
    // Get submitted data
    $data = FormSpring::request($api_key, 'data', $parameters);
 
    // Update the number of pages
    $pages = $data['pages'];
 
    // Iterate over each entry
    foreach ($data['submissions'] as $submission) {
 
        // ....
    }
 
    // Increment the page # for the next request
    $parameters['page']++;
}

Within the submission loop, we create a new event for each form submission, then add that to the calendar using the Zend library.

// Iterate over each data item to get the event information
$event = array();
foreach ($submission['data'] as $item) {
    if (isset($fields[$item['field']])) {
        $field = $fields[$item['field']];
        $event[$field] = $item['value'];
    }
}
 
// Create a new calendar event
$newEvent = $gdataCal->newEventEntry();
$newEvent->title = $gdataCal->newTitle($event['title']);
$when = $gdataCal->newWhen();
$when->startTime = date3339($event['start']);
$when->endTime = date3339($event['end']);
$newEvent->when = array($when);
 
// Add the event to the calendar
$createdEvent = $gdataCal->insertEvent($newEvent);

You’ll need to refresh your calendar to view new events, and can edit them just like you would any other ones.

That’s it for our series on FormSpring-Google mashups. Feel free to comment below if you have any questions, ideas for mashups you’d like to see, or links to ones that you’ve built yourself.Recent Posts:

• FormSpring Launches New Data/Report Features
• Make Your Event Registration Form Tweet
• How To Embed Google Analytics Into Your Form

Other Interesting Posts

• Continued Learning With FormSpring
• Adding Form Field Variables to E-mail Subject Lines
• New Version of FormSpring Set to Launch

This is the second of three Google mashup articles this week for programmers who want to explore the new FormSpring API. If you haven’t seen it yet, take a look at yesterday’s Google Maps mashup.

Today’s mashup involves updating a Google Spreadsheet with collected form data. It might be advantageous to do this over regularly exporting data to Excel or another spreadsheet in a manual fashion — once the integration is setup, you can work within an online spreadsheet and see new rows added shortly after a form’s submitted.

Feel free to download the PHP code and follow along. The example code uses the Zend Framework PHP Client Library to access the Google Spreadsheets API. You’ll need to download the Zend framework in order to use this.

To get started, sign up for a Google account and create a spreadsheet that will be used to store data collected in the FormSpring form. You’ll also need to create a FormSpring API key that has data access to your form. In the spreadsheet, create a header row that matches the field labels in your form. The script will look at that header row to figure out what data should be copied. For example, if the script sees a column titled “First Name”, the data from the field labeled “First Name” will be added to the appropriate cell.

In the PHP script (example.php in the download), we’ll first use the Zend library to log in to Google using a username and password:

$authService = Zend_Gdata_Spreadsheets::AUTH_SERVICE_NAME;
$httpClient = Zend_Gdata_ClientLogin::getHttpClient(
    $google_username, $google_password, $authService);
$gdClient = new Zend_Gdata_Spreadsheets($httpClient);

The example gets a list of all the spreadsheets in the account, and finds the one we want to update. Once the spreadsheet name is found, we save the key to use later.

$feed = $gdClient->getSpreadsheetFeed();
foreach($feed->entries as $entry) {
    if ($entry->title->text == $spreadsheet_name) {
        $id = split('/', $entry->id->text);
        $spreadsheet_key = $id[5];
    }
}

We’ll need to do the same thing to find the right worksheet within the spreadsheet, but can assume that most of the time the first worksheet will be used.

$query = new Zend_Gdata_Spreadsheets_DocumentQuery();
$query->setSpreadsheetKey($spreadsheet_key);
$feed = $gdClient->getWorksheetFeed($query);
$i = 0;
foreach($feed->entries as $entry) {
    if (
        (empty($worksheet_name) && $i == 0) || 
        (!empty($worksheet_name) && $entry->title->text == $worksheet_name) 
    ) {        
        $id = split('/', $entry->id->text);
        $worksheet_id = $id[8];
    }
    $i++;
}

Once we’ve found the worksheet, we can get the header row and save the contents to try to match up to the form field labels.

$header_cells = array();
$query = new Zend_Gdata_Spreadsheets_CellQuery();
$query->setSpreadsheetKey($spreadsheet_key);
$query->setWorksheetId($worksheet_id);
$query->setMaxRow(1);
$feed = $gdClient->getCellFeed($query);
foreach ($feed->entries as $entry) {
    $header_cells[] = $entry->content->text;
}

Now we query the FormSpring API in order to get information about the form, including a list of fields on the form with their labels and id. We’ll loop over the list of fields and find the ones that exist in the spreadsheet. We’ll also store a modified version of the field name which is used by the Google Spreadsheets API to reference each column (e.g. firstname instead of First Name).

// Get information on the FormSpring form
$form = FormSpring::request($api_key, 'form', array( 'id' => $form_id ));
 
// Map form field ids to worksheet column names
$fields = array();
foreach ($form['fields'] as $field) {
    if (in_array($field['label'], $header_cells)) {
        $fields[$field['id']] = strtolower(str_replace(' ', '', $field['label']));
    }
}

After figuring out how to match up form fields with spreadsheet cells, we can start fetching submitted data. Assuming that this script will be scheduled to run in cron on a regular basis, we’ll need some mechanism to make sure that we don’t add old data to an existing spreadsheet. For the sake of simplicity, in the example we do that by downloading the prior day’s worth of submissions and assume that the script will only run once a day. The min_time and max_time parameters (which search against the submission date and time for each record) can easily be changed to do this on an hourly basis, or even better, we can locally store the unique id of the last submission so that we know the same submission is never added to the spreadsheet twice.

When downloading the submitted data only a pre-defined number of results (25 by default) are returned at each time, and we’ll need to make multiple requests to the API to download each “page” of results.

// Loop through each page, making one query per page of data
$pages = 1;
while ($parameters['page'] <= $pages) {
 
    // Get submitted data
    $data = FormSpring::request($api_key, 'data', $parameters);
 
    // Update the number of pages
    $pages = $data['pages'];
 
    // Iterate over each entry
    foreach ($data['submissions'] as $submission) {
 
        // ....
    }
 
    // Increment the page # for the next request
    $parameters['page']++;
}

Within the submission loop, we build a row of data that will get inserted into the spreadsheet. The row is stored as an array with the column name as the key and the submission data as the value.

$row = array();
foreach ($submission['data'] as $item) {
    if (isset($fields[$item['field']])) {
        $col = $fields[$item['field']];
        $row[$col] = $item['value'];
    }
}

Once the row is created, it can be added to the spreadsheet using the Zend library.

$entry = $gdClient->insertRow($row, $spreadsheet_key, $worksheet_id);
if ($entry instanceof Zend_Gdata_Spreadsheets_ListEntry) {
    print "added row {$entry->id->text}\n";
}

You should see the data update within the Google Spreadsheets interface in real time while the script runs, and can be sorted, formatted and revised just like any other spreadsheet.

Feel free to comment below if you have any questions about this example. Check back tomorrow for another Google mashup example.Recent Posts:

• FormSpring Launches New Data/Report Features
• Make Your Event Registration Form Tweet
• How To Embed Google Analytics Into Your Form

Other Interesting Posts

• Five Minutes with Noah Coffey
• Out of Office Friday, July 3rd
• Make Your Event Registration Form Tweet

The FormSpring API is now live, and available to anyone with an account. To create a key to use with your forms, log in to the admin interface, go to Your Account then click on the API section. We’ve put together some online documentation to help you get started, along with some example PHP code (more languages coming soon).

In this article, I’m going to walk you through an overview of the creation of a mashup application that uses the FormSpring and Google Maps APIs. It’s the first of three Google mashups that we’ve put together this week to help programmers better understand the API, and hopefully spark some creative ideas on ways you can use FormSpring with other web applications. Today’s mashup will take addresses submitted with a form and display the locations on an interactive map. For example, if you create a registration form for an event you’re holding, you can use this to easily display where your registrants are coming from. Feel free to download the source code and follow along.

The first thing to do is create your form with the appropriate address fields. The one used in this example has text fields for address, city and zip code, and a select list for U.S. states.

Now you’ll need to create an API key with data access to that form. Log into your account as described above to create the key. You’ll also need to create a Google Maps API key in order to geocode the addresses and display the map.

There are a lot of ways to use the Google Maps API, but what we’re going to do in this example is create a static HTML file with JavaScript code that displays the map, while the points on the map are fetched from an XML file. The file will be generated with a PHP script that gets submitted form entries, sends each address to the Google Map geocoder to translate them to a latitude/longitude point, and outputs something like this:

<markers>
    <marker lat="39.905285" lng="-86.087273" />
    <marker lat="39.905186" lng="-86.051196" />
    <marker lat="39.926901" lng="-86.066278" />
</markers>

In the PHP script (data.php in the download), we’ll first make a request to the API’s form method to get information about all the fields on the form, in order to map field ids to labels (e.g., so we know the City field is the field with ID 100001).

// Get information on the FormSpring form
$form = FormSpring::request($api_key, 'form',
    array( 'id' => $form_id ));
 
// Map field ids to labels
$fields = array();
foreach ($form['fields'] as $field) {
    $fields[$field['id']] = $field['label'];
}

Now we make a second request to the API to retrieve submitted entries from the form:

// Get the 1st page of submitted data for the form
$data = FormSpring::request($api_key, 'data', array('id' => $form_id));
 
// Iterate over each entry
foreach ($data['submissions'] as $submission) {
 
    // ...
}

As we loop over each submission we create a geocoder query string by combining address, city, state and zip code values. We’re going to request a CSV formatted response from the geocoder, which is described in detail here.

// Make a request to Google's geocoder to get address lat/long
$csv = file_get_contents('http://maps.google.com/maps/geo?q=' .
    urlencode($address) . '&output=csv&key=' . $maps_key);
 
// Parse the first line of the CSV response
$lines = explode("\n", $csv);
$res = explode(',', $lines[0]);
 
// Add this point if the status code was successful
if ($res[0] == 200)
    print '<marker lat="'. $res[2] .'" lng="'. $res[3] .'" />'."\n";

Now that the XML file is being generated with points for each address, you need to create the HTML and JavaScript to display the map. In the HTML file, you can start with the Hello World example from the Google Maps API documentation. Now use the GDownloadUrl() method to point to data.php, parse the XML and add a marker for each entry:

GDownloadUrl("data.php", function(data, responseCode) {
    var xml = GXml.parse(data);
    var markers = xml.documentElement.getElementsByTagName("marker");
    for (var i = 0; i < markers.length; i++) {
        var point = new GLatLng(
            parseFloat(markers[i].getAttribute("lat")),
            parseFloat(markers[i].getAttribute("lng"))
        );
        map.addOverlay(new GMarker(point));
    }
});

Once that’s done, you should have a map that looks something like the image below (this shows all the Starbucks within a 2 mile radius of our offices):

If you use this on a live site, you might want to setup a cron job to run the PHP script and save the output to a static XML file every few minutes, then point to that file instead. That would speed up the rendering process dramatically, and ensure that you don’t reach the maximum number of requests for your API keys if the site gets heavy traffic.

That’s all. Feel free to comment if you have any questions or suggestions. Check back tomorrow for another example.

Recent Posts:

• FormSpring Launches New Data/Report Features
• Make Your Event Registration Form Tweet
• How To Embed Google Analytics Into Your Form

Other Interesting Posts

• Meet Us at SXSW at the SXSBW Happy Hour
• New Version of FormSpring Set to Launch
• FormSpring Launches New Data/Report Features

We’ve been working on creating the new FormSpring API, and are currently looking for beta testers to try it out and give us feedback. The API will let programmers add, edit and retrieve data stored within your FormSpring account, and currently returns data in XML, JSON and serialized PHP.

If you’re interested, please read through the API documentation and fill out this contact form so we can give you access to start using the API.

The full launch of the API is tentatively scheduled for mid-September. Stay tuned for more news.Recent Posts:

• FormSpring Launches New Data/Report Features
• Make Your Event Registration Form Tweet
• How To Embed Google Analytics Into Your Form

Other Interesting Posts

• Personalized responses
• Linking Vs. Embedding Vs. HTML
• FormSpring User Profile: Custom Fitness Concepts