PDF In-Depth

Web Hosting PDFs

October 15, 2003

Advertisement
Advertisement
 

The purpose of this article is to explore the concept of PDF Forms as the User Interface for real-world applications on the Web. We will review the creation process for a PDF form, and walk-through a sample Active Server Pages (ASP) script to collect the data, before reviewing an ASP script that can parse this information, act on it, and return results to the client.

Adobe Acrobat allows you to create electronic forms that maintain your organisation's branding. You can either design and create a new form from scratch, or convert existing forms to PDF and then add PDF form fields. One of the major benefits of PDFs is their visual integrity: unlike an HTML form, a PDF form can look identical to its estranged paper-based cousin. Others have detailed exactly how to go about creating rich PDF forms that include JavaScript for validation and usability, so we'll concentrate on how PDF Forms interact over the Internet with a Web server.

In simple terms, a form -- whether PDF or otherwise -- provides a way of filtering information from a user into a format which is usable to you. Of course, secondary benefits arise when you can then take that information and do something with it. For example, you could update your database and subsequently produce a report based on that data.

What we are going to look through now is how you can create a PDF Form suitable for collecting data and submitting to a server.

Staying with the theme of real-world examples, let's pretend that we want to create a system that handles the redirection of data from a simple PDF form to an email address of our choosing.

Since the advent of Acrobat 5.0, PDF form data can be submitted in one of two formats: the traditional Forms Data Format (FDF) or XML Forms Data Format (XFDF). Of the two, FDF is the variant that is most similar to the internal structure of a PDF itself, whereas XFDF comprises the same data structured using XML syntax. For those programmers already familiar with parsing and working with XML, XFDF is likely your best bet, whereas FDF traditionalists will advocate sticking to FDF.

Note: If you host your Web site with a shared hosting service then you may find that the hosting provider is reluctant to load the FDF Toolkit onto their server. In this case, you might need to consider using the XFDF Toolkit and generic XML parsing routines. Don?t forget that this will limit you to Acrobat 5.0 and greater, although this poses less of a problem with the release of Acrobat 6.

What is FDF?

FDF is the file format used for Acrobat Forms and is used when submitting Form data to a server, receiving a response, and incorporating it back into a Form.

Let's assume that you're working with FDF for the moment. The first thing that you're going to need is the FDF Toolkit. Whilst the Adobe Acrobat SDK is something that you're going to want to have on hand -- you'll also need a current ASN membership in order to access the complete SDK in all its glory -- the FDF Toolkit is actually a separate download that you can pick up from the Adobe web site. Unfortunately, the FDF Toolkit is temporarily unavailable while Adobe completes the Acrobat 6 version, but it should be back soon.

What is the FDF Toolkit?

The FDF Toolkit is a threadsafe API for writing server applications to generate or parse FDF data from a form created by the Adobe Acrobat Forms Plug-in. The FDF Toolkit can be used on Microsoft Windows or UNIX platforms, and supports the C/C++, ActiveX (e.g. VB, ASP, .NET etc.), Java, and Perl development languages.

How do forms work?

Once the user fills out the PDF-based form, the data is submitted to a server for processing. A server-side application can then parse the data from the form fields using the FDF Toolkit. Once the data has been processed, you can use FDF to generate a response acknowledging that some action has taken place to the user.

Server Preparation

Much like a master chef, we need to make sure that we've adequately prepared our work area before we get too involved the fine detail, including the equivalents of chopping all of our ingredients and reading the recipe.

For the purposes of this particular sample, you're going to need to make sure that you have a copy of the full version of either Acrobat 5.x or Acrobat 6.0 Professional on either Mac or Windows. You will also need full administrative access to an Internet Information Server 4.0 (IIS) or higher to set this up.

Download and install the FDF Toolkit ensuring that you pay particular attention to the permissions-related steps. These items can certainly be a trap for first time players, and if this isn?t your area of expertise then you might like to draw upon a friend or acquaintance that is handy with System Administration.

Creating a simple PDF Form

In this case, we're going to create a simple form for capturing feedback for visitors to our Planet PDF Web site.

The information that we'll need to request from the user is:

  • First Name
  • Last Name
  • Company
  • Email Address
  • Country
  • Comment

To keep things simple, let's start with a single page blank PDF. Whilst you can produce a simple blank PDF from a blank page in Microsoft Word, SimpleText or Windows Notepad, we prefer to use the built-in JavaScript console. See tip.

Tip: Create a clean blank document the easy way! Press Ctrl-J on Windows or Apple-J on the Mac (Acrobat 5 Mac users should also use Ctrl-J) to popup the JavaScript console. Type app.newDoc(XXX,YYY); and press the enter key on the numerical keypad.Voila! An instant new page.

Lay out the form fields using the Form Tool within Acrobat.

Select the Forms Tool and create a text field. Name the field, ?First.Name? Do the same for each of the following fields using the text in brackets below as the field name.

  • First Name (First.Name)
  • Last Name (Last.Name)
  • Company (Company)
  • Email Address (EmailAddress)
  • Country (Country)
  • Comment (Comment)

Tip: You can add text to a blank page using the Text Annotation Tool. If you want to make it part of the page contents then you can use the JavaScript console command this.flattenPages(); BEWARE: this powerful command will flatten all objects on a page including any forms fields that you had painstakingly laid out. Be sure to do this before adding any other interactive elements. Third Party Tools such as Quite A Box of Tricks from Quite Software provide the ability flatten only annotations and not form fields and vice versa.

Note: If you are using Acrobat Approval, Acrobat 6.0 Standard or Adobe Reader 6.0 with an appropriately enabled document, then you cannot create forms; you can only fill them. In order to create forms you need the full version of either Adobe Acrobat 5.x or Adobe Acrobat 6.0 Professional, and definitely not the free Reader.

OK, now we've added all the data elements that are required, we're also going to need to add a control field that contains the routing information for this form. Specifically, we're looking to add a hidden field containing the email address to which to forward this information.

Use the Form Tool to create a text field that contains a default value of "info@planetpdf.com". At the base of the first tab, you'll see a Hidden Field Checkbox. Make sure that this is checked on. Move the form field to an inconspicuous area of the form. Our server side script is going to be inspecting this value to work out exactly where to send this data.

The final step in creating our client-side form is to add a Submit button to point to our server. Use the Form Tool to add another form field to your form. Change the Type selector to button, and use the name Submit. Change to the action tab and add a Submit Form action.

For the URL, you can either use your own server (assuming that you've correctly configured and set up your script, or you can use the public demonstration that we are hosting at Planet PDF.

Set the URL to be "http://www.planetpdf.com/planetpdf/asp/fdfgateway.asp#FDF" Our client side form is mostly complete. Now we're ready to take a look at what's required on the server side.

Note: When you specify your URL in the Submit Form action, be certain that you add the #FDF text. Doing this ensures that your Web browser correctly passing back the response it receives from the Web server to Acrobat rather than trying to handle it by itself (which it wouldn?t do fantastically well, since it doesn?t understand PDF).

Server Side

Since we've already confirmed and installed the FDF Toolkit as part of preparation, let's get straight to the general approach we've taken to solve this problem.

The idea behind the FDFGateway script is simple, it's a generic extensible script that takes any form data and forwards it via email to the SMTP address specified in the required field ?mailto?.

It operates by using the FDF Toolkit to open the incoming FDF from the binary buffer. It then checks to see if field mailto is present. If not, it formats a simple error message and returns this to the user by way of the FDFSetStatus method, which instructs Acrobat to pop up an alert box to the user. If the mailto field is present, then the script formats a simple email using the Collaborative Data Objects (CDONTS) ActiveX component provided with Internet Information Server 4.0 and above.

Let's step through the code slowly to see exactly how this operates;

The first thing we need to do is to instantiate the FDF Toolkit so we can direct it to our work for us. To do this we use the CreateObject method of the Server object. The class string for the FDF Toolkit is ?FdfApp.FdfApp?.

' Create the FDF App Object
    Set FdfAcX = Server.CreateObject("FdfApp.FdfApp")

Now we need to load our instance of the FDFToolkit with our data for further processing. Since the FDF data is presently contained within the buffer of the Request object, we'll use the FDFOpenFromBuf method of the FDFToolkit.

    Set objFdf = FdfAcX.FDFOpenFromBuf(Request.BinaryRead(Request.TotalBytes))

Acquire the contents of the only required field, ?mailto? by making a call to FDFGetValue. Note the requirement to wrap the call in instructions to the ASP error handler. See the tip for more details.

    on error resume next
    strMailTo = objFdf.FDFGetValue("mailto")
    on error goto 0

Tip: Wrap your calls to FDFGetValue in on error resume next and on error goto 0 to ignore exceptions raised by the FDFToolkit when a field value is not present.

At this point, you could validate the email address specified or otherwise verify that all is well. Assuming that everything is all ok then we need to go on and forward this data to the specified recipient. In this case, we're going to do this by way of creating an email with an FDF attachment.

Use the ASP FileSystemScripting object to write the contents of the buffer to a file. We're going to use a temporary file and folder for this purpose since we don?t need or want to retain the data on the server.

	Dim fso
	Set fso = CreateObject("Scripting.FileSystemObject")
	Set strTempfolder = fso.GetSpecialFolder(2)
	strTempFile = fso.GetTempName()
	strTempFile = left(strTempFile, len(strTempFile)-4)
	strTemp =  strTempFolder & "\" & strTempFile & ".fdf"
	objFdf.FDFSaveToFile strTemp

Now we need to create, format and send the email containing the attachment. In the example below, I've used the CDONTS library. You could use any SMTP-based component for sending email via ASP at this point.

	Set myMail = CreateObject("CDONTS.NewMail")
	myMail.From = "formsonline@planetpdf.com"
	myMail.To = strMailTo
	myMail.Subject = "Planet PDF: Forms Data Received"
	myMail.Body = strMessage
	myMail.AttachFile strTemp, "PlanetPDF.fdf"
	myMail.Send
	Set myMail = Nothing 

We're almost done now; all that's required is to provide the user with some direct feedback to let them know what's happened. The most convenient way to do this is by way of the FDFSetStatus method. This pops up an alert box on the client side and provides a mechanism for feedback without having to create a multitude of PDFs to send back and forth.

	' Add Advertising
	strStatus = "This forms data was processed by Planet PDF "

	Set objFdf = Nothing
  	set objFdf = FdfAcX.FDFCreate
	objFdf.FDFSetStatus strStatus

That's it - we're done! Here's the entire script pasted below with some simple error handling in place.

< %@ Language=VBScript %>
< %

	Option Explicit
'	Declare all our variables as it speeds things up and is generally good practice

    	Dim FdfAcX
    	Dim objFdf
Dim strMailTo
	Dim strMailFrom
	Dim strStatus

' Create the FDF App Object
    Set FdfAcX = Server.CreateObject("FdfApp.FdfApp") 

' Open the FDF file from the buffer - this is the preferred method
' Note:You need to have Windows NT Service Pack 3 (SP3)
' installed for this to work. SP3 includes version 1.0b of
' ASP, which adds Request.BinaryRead and
' Request.TotalBytes.

    Set objFdf = FdfAcX.FDFOpenFromBuf(Request.BinaryRead(Request.TotalBytes))

' Get the first name

' *** The "on error resume next" line is to avoid an error that occurs when the field 
contents are blank 

    on error resume next
    strMailTo = objFdf.FDFGetValue("mailto")
    on error goto 0

    on error resume next
    strMailFrom = objFdf.FDFGetValue("mailfrom")
    on error goto 0

 ' Validate MailTo
	if strMailTo <> "" then
	Dim strTempFile
	Dim strTempFolder
	Dim strTemp

	Dim fso
	Set fso = CreateObject("Scripting.FileSystemObject")
	Set strTempfolder = fso.GetSpecialFolder(2)
	strTempFile = fso.GetTempName()
	strTempFile = left(strTempFile, len(strTempFile)-4)
	strTemp =  strTempFolder & "\" & strTempFile & ".fdf"
	objFdf.FDFSaveToFile strTemp

	' Send FDF file
	Dim myMail
	Dim strMessage

	' Add from address if provided	
	if strMailFrom <> "" then
		strMessage = "Please find attached forms data from " 
& 
strMailFrom & chr(13) & chr(13) & "Processed by Planet PDF 
"
	else
		strMessage = "Processed by Planet PDF "
	end if

	Set myMail = CreateObject("CDONTS.NewMail")
	myMail.From = "formsonline@planetpdf.com"
	myMail.To = strMailTo
	myMail.Subject = "Planet PDF: Forms Data Received"
	myMail.Body = strMessage
	myMail.AttachFile strTemp, "PlanetPDF.fdf"
	myMail.Send
	Set myMail = Nothing 	

	' Delete temporary file
	fso.DeleteFile strTemp 
	Set fso = nothing

	' Add Advertising
	strStatus = "This forms data was processed by Planet PDF "
	else
	strMailTo = "undeliverable@planetpdf.com"
	strStatus = "Sorry, this form does not contain a mailto: 
address for processing"
	end if	

	Set objFdf = Nothing
  	set objFdf = FdfAcX.FDFCreate
	objFdf.FDFSetStatus strStatus

' Send back the FDF
    Response.ContentType = "application/vnd.fdf"
    Response.BinaryWrite objFdf.FDFSaveToBuf

' Clean up our objects
    Set objFdf = Nothing
    Set FdfAcX = Nothing

    Response.End
%>

MORE INFO

PDF In-Depth Free Product Trials Ubiquitous PDF

Debenu Quick PDF Library

Get products to market faster with this amazing PDF developer SDK. Over 900 functions and an equally...

Download free demo

Two Passwords Are Better Than One: The Low-Down On PDF Security

For people who don't spend their time looking at PDF files in text editors*, PDF security is a sometimes misunderstood beast.

For example, those document restrictions that PDF files sometimes have -- no Printing, Content Copying, Page Extraction, etc -- are essentially useless unless the PDF also has a User Password.

January 09, 2014
Platinum Sponsor



Search Planet PDF
more searching options...
Planet PDF Newsletter
Most Popular Articles
Featured Product

Debenu PDF Aerialist 11

The ultimate plug-in for Adobe Acrobat. Advanced splitting, merging, stamping, bookmarking, and link control. Take Acrobat to the next level.

Features

Adding a PDF Stamp Comment

OK, so you want to stamp your document. Maybe you need to give reviewers some advice about the document's status or sensitivity. This tip from author Ted Padova demonstrates how to add stamps with the Stamp Tool along with related comments.