By Thom Parker May 7, 2006
Scope: All Acrobat versions
Skill Level: Intermediate
Prerequisites: Familiarity with Acrobat forms
Acrobat provides several methods for moving data in and out of a form. The most reliable and flexible of these methods is direct submission to a web server with the submitForm() function. It’s reliable because it uses a standard HTTP POST or GET to send and receive data to and from a web server. These are exactly the same operations a standard browser uses to request a web page. The only requirements are that the user has a network connection and that there is a server script on the other end for receiving and sending form data. The submitForm() function is flexible because it has a large variety of input arguments for configuring just about any kind of data format, including sending non-traditional data such as commenting annotations, images, the entire PDF, and custom XML formats.
Other options for moving data are emailing form data, writing it to an ODBC database, and saving form data to a file on the user’s local hard drive. Emailing data is often desirable because it does not require a server script, but it relies heavily on the individual user’s system setup and may not work consistently for all users. ODBC access and saving to the user’s hard drive can only be done from a Rights Enabled PDF, Acrobat Standard, or Acrobat Professional, options rarely available to everyone involved.
The only input required to use the submitForm() function is the cURL argument. This is, of course, the URL of the server script that will process and/or return the form data. When this is the only argument used the form data is submitted in FDF format. FDF is the original data format developed for Acrobat and PDF. It is text based and can contain much more than plain form data. It can contain anything inside a PDF. The following line of code does a simple submit to a server script. This particular script is written in ASP.NET, but it could be any server scripting language, PHP, Perl, Java, etc. It is only important that the script handle the PDF data.
The submission URL can also be configured to send data via email. This is not just an alternate method for email submission. The submitForm() function provides many more data formatting options than the mailForm() function, so it offers much finer control over the submitted data. The following line of code shows the syntax for email submission with parameters for setting the cc, bcc, subject, and body of the email. The body parameter is the same as the message text.
this.submitForm( "mailto:[email protected]?" + "[email protected][email protected]" + "&subject=good news" + "&body=The order is in!" );
The next most useful input parameter is cSubmitAs. This argument controls the format of the submitted data. It was introduced in Acrobat 6.0 and overrides several individual parameters used in earlier versions that accomplish the same task. There are 7 choices, shown in the table below.
Original PDF Data Format - Similar in structure to the PDF format, it can hold any PDF structure and is the most flexible of all the data formats
XML version of FDF with much reduced functionality
HTTP Get style Name/Value Pairs, only works for small data
LiveCycle Designer XML Data Package format, native to XFA forms
Simple XML representation of data. Follows XDP conventions
A Different Style of presenting XFA form data, similar to XDP
| || |
Entire contents of the PDF File
Two of these formats, FDF and XFDF, were designed specifically to work with traditional AcroForm documents, and two of the formats, XDP and XFD, were designed specifically for XFA (LiveCycle Designer) documents. However, as strange as it might seem, all of the formats (except HTML) can be both submitted from and consumed by both types of PDF forms, although not always cleanly or with the desired results.
The HTML option is just a way of telling Acrobat to use an HTTP Get request to submit the data. With this option the form data is appended to the submission URL using the standard GET style of presenting name/value pairs. Obviously, this technique is severely limited due to restrictions on URL lengths by the various software components that must handle them. It should only be used for simple forms.
The PDF option submits the entire contents of the PDF in the body of the HTTP Request. This is required for preserving documents with digital signatures, setting up Reader based document reviews, or for simply transferring the entire document. This option can only be used in Adobe Reader if the document has Save Rights.