How We Did It: Part 2 – The Ultimate Tourney Guide

| No Comments

This article is Part 2 of 5. Please read Part 1 if you have not done so already.

Note: As of March 19th 2009 the Ultimate Tourney Challenge on ESPN.com is no longer open for entries. However, you can still download the “Ultimate Tourney Guide” and track the progress of the tournament.

Part 2
As promised, this article discusses how we were able to use the Forms Data Format (FDF) to allow the “Ultimate Tourney Guide” to display your personalized fantasy bracket on ESPN.com.

As a reminder from part one, in order to display your fantasy bracket, the PDF file needs to request a personalized RSS feed from ESPN. Once you have the XML response, displaying the data is easy with a little Flex programming. To instrument the PDF file, we needed to find a way to get a unique identifier into the PDF file without the user being required to sign into ESPN.com every time. Well, for those of you who are familiar with Acrobat forms, the solution is probably obvious; FDF of course.

Note: The following discussion of Acrobat Forms and FDF does not apply to LiveCycle Designer Forms (XFA) .

If you are familiar with how FDF files work, skip to Accessing the Field from the Embedded SWF: [link]

FDF Files Demystified:
To better understand what and FDF file is and how it was useful in creating the Ultimate Tourney Guide, a short history lesson might be helpful. We added the ability to have form field widgets (Acrobat Forms) in version 3.0 of Adobe Acrobat and Adobe Reader.

Back then, it wasn’t very easy to get HTML to represent a form in a way that easily replicated the paper version; in many respects it still isn’t. In order to allow form developers to easily replace a basic HTML form with a highly formatted paper-like PDF form, we engineered the Acrobat Forms “submit” button in such a way that you could send data to a server script as a query string. In this way, the server had no idea that the data was being sent from a PDF. As long as you authored your PDF form so that the field names in the PDF matched the field names in the original HTML, everything just worked without changing anything on the server. That took care of sending data to the server.

Populating a PDF with Form Data from a Server:
At that time, if you wanted to pre-populate an HTML form with data, you served the HTML with the field values already set in the field tag. You couldn’t do this with Acrobat Forms because you couldn’t simply redraw the PDF with the field values already present like you can with HTML.

In order to allow developers to send field values to Acrobat Forms from a server, we created FDF. FDF has evolved through the years but it can still be just a simple text file that contains field-name, field-value pairs. When most people open an Acrobat Form from a server with personalized information already in it, based on what happens on the screen, they may think that the server added their information to the PDF file. If an FDF file was used to accomplish this, the opposite is actually true; the PDF file was added to the data.

“Excuse me?”

Yes – that’s correct. The PDF file was added to the data. FDF files, specifically the one we used for the Ultimate Tourney Guide, can contain a pointer to the PDF that the data belongs to. In the case of the Ultimate Tourney Guide, the users click on a link on an HTML page, a script then generates an FDF file and returns that back to the browser. The mime type of an FDF file is “application/vnd.fdf” and when you install Acrobat or Reader, the installer configures your browser to use these products to open FDF files. When one of our viewers reads the FDF file, it looks for something called the “/F” or “/UF” key to locate the PDF file that the data should be merged into. Below is an example of what the FDF file from this project looks like. I’ve modified the actual values but the structure is the same.

Example FDF with a unique ID field-name field-value pair

%FDF-1.2
1 0 obj
<
<</Fields[
<<
/T(uniqueID)/V(62FBDDE3-25BA0473CC8D)
>>
]
/UF(http://www.myhost.com/ultimateTourneyGuide2009.pdf)
>>
/Type/Catalog>>
endobj
trailer
<>

The FDF file above will insert the value “62FBDDE3-25BA0473CC8D” into the field named “uniqueID” in the PDF file located at “http://www.myhost.com/ultimateTourneyGuide2009.pdf”. Now, I am in no way suggesting that you use FDF files for your more typical electronic forms workflows; we have LiveCycle Designer and the LiveCycle Server products for that. The kind of FDF file that we needed for this project was simple enough that it works well and it was easy to generate using the existing server environment at ESPN.com.

Finally, because we added the ability for Ultimate Tourney Guide to save form data using the free Adobe Reader, when you save it to your desktop, the uniqueID field value is saved with the file. With the uniqueID saved into the PDF file, it will be able to access your RSS feed from ESPN.com without needing to log in each time.

You can read more about how data flows into a PDF file using FDF files in the “Forms System Implementation Notes” which is part of the FDF Toolkit documentation.

Note: There is no direct link to the “Forms System Implementation Notes”, you’ll need to download the FDF Toolkit, unzip the files and locate “FormSys.pdf” in the “documentation” folder.

Accessing the Field from the embedded SWF:
The application that we use to display the bracket information was written using Flex Builder 3 and was placed into the PDF file using the new Multimedia Flash tool. Because the PDF file is the container for the SWF application, it is very easy to access properties of the PDF file or objects within it. As I have discussed in earlier posts, you can use the ExternalInterface class to query the PDF file for any string value that you can access through the Acrobat JavaScript API. The following ActionScript code will set the value of the “extCall” variable in the SWF application to the value of the uniqueID field in the PDF file.

var javaScript:String = “this.getField(‘uniqueID’).value”;
var extCall:String = ExternalInterface.call(‘eval’, javaScript);

Now that we know what the uniqueID is, we can finally construct the URL, request the personalized RSS feed, process it and display the bracket… assuming, of course, that you are still viewing the PDF file in the browser.

Conclusion: Accessing the RSS Feed when Opening the PDF file from the Desktop:
If the PDF file requesting the data is in the same domain as the server that is supplying the data, everything just works as you would expect. When you first opened the Ultimate Tourney Guide this was true. However, if the PDF file is opened from the desktop, a “*” crossdomain.xml policy file is required on the server for Acrobat or Reader to be permitted access. The Security Model for our version 9 viewers has been greatly improved to make your browsing experience more safe and secure. Because security is such an important topic, I’m going to save this discussion for part 3. Until then, you can get details on how the security model affects SWF applications running inside a PDF file in the Technical White Paper “Security for Flash Player compatible content in Acrobat 9”.

Read Part 3