FDF (Forms Data Format) is for transferring data to and from PDF forms on the web, right?
While this is one of the most common and best documented uses, other applications for FDF
are myriad, including: populating PDF forms offline with Reader, enabling PDF features that
cannot be enabled through the Acrobat user interface, automating changes to forms, modifying
form field attributes, creating enhanced form fields, and accessing undocumented features.
In this article, I will present an approach that uses FDF files for some of these less
common purposes, through the practical example of using form buttons for >Go to View actions. (For more information on FDF, the FDF
Toolkit documentation (1) and Appendix H of the Portable Document Format Reference Manual is
Using Buttons for Links
Have you ever wanted to use a Go to View action with
a form button to link to an external PDF document? Although allowed in PDF and supported by
Acrobat, there is, unfortunately, no user interface in Acrobat for specifying what the PDF
Reference Manual calls GoToR (GoTo Remote) actions with
form fields. Why this limitation? Because the Field
Properties window is, by necessity, a modal dialog, which must be closed before
any other interaction with Acrobat is possible. This is in contrast to the Link Properties and Bookmark
Properties windows, which allow you to navigate to a location in another document
to set the page number and view, or named destination, to create a Go to View action.
A common workaround for this limitation of the Acrobat user interface is to use a
read-only button and create a link annotation around it. While this works, it unnecessarily
increases the size of the PDF file and involves a greater effort to implement. Another
workaround is to use an Open File (i.e., Launch) action
to ‘link’ to an external PDF document. This also works, but you lose the flexibility of
being able to specify an exact location and view in the target document, since you are
limited to opening the target file to whichever page number and magnification is specified
in the Open Info window (File > Document Info > Open).
Buttons have a number of advantages over link annotations, most of which relate to the
greater range of options in their appearance and behavior. For example, you can use a button
buttons can be created and manipulated using Visual Basic and the Forms API with Acrobat 4,
thus providing an accessible means of automation. This is not the case for link annotations,
although a number of Acrobat plug-ins are available for manipulating links.
Anatomy of a GoToR Action
The PDF Reference Manual lists four possible keys for the
|/S||Subtype, always GoToR|
|/D||Destination in target
|/F||File specification of target
|/NewWindow||Determines whether or not the
target PDF is opened in a new window.
The S key is required and it’s value must be equal to
GoToR. Enough said.
The required D key specifies the target destination,
which can either be a named destination that is present in the target PDF, or a page
number and view specified in an array. Several examples are shown below. For more
information, see pages 184-185 of the PDF Reference Manual.
|Link to named destination
|/D [ 20 /XYZ null
null null ]
|Link to page 21, retain
|/D [ 20 /XYZ 0
396 2 ]
|Link to page 21, middle of page,
zoom to 200%
|/D [ 9 /Fit ]||Link to page 10, ‘Fit in Window’|
|/D [ 1 /FitH -32768 ]||Link to page 2, ‘Fit Width’|
|/D [ 4 /FitV 0 ]||Link to page 5, fit height of
page to the window
|/D [ 4 /FitB ]||Link to page 5, fit page’s
bounding box to the window
The required F key is the file specification of the
target PDF. This can take on a number of forms, which the PDF Reference Manual discusses in
detail. The following table shows examples of file specifications for several typical
scenarios, using the DOS file system:
The NewWindow key is optional and allows you to
specify a link that overrides the Open Cross-Doc Links in Same
Window user preference (File > Preferences > General). If this value is
true, the user preference is ignored and the target document
is opened in a new window. If this value is false, the
user preference is ignored and the source document is closed before opening the target
document. If this key is not present, the user preference is honored. This is another
example of enabling a PDF feature that is supported by Acrobat but which you are unable to
activate via the Acrobat user interface, even for link annotations.
Wrap it Up in FDF
Now that we know what’s involved in specifying a Go to
View action, we’re ready to construct an FDF file that can be used to assign such
actions to form fields. Below is an example of an FDF file that will make the action
assignments when it is imported into a form.
1 0 obj
/FDF << /Fields
<< /T (button1)/A << /S /GoToR /D (Section8)/F (pdf2.pdf)/NewWindow true >> >>
<< /T (button2)/A << /S /GoToR /D [1 /XYZ null null null]/F (../pdf2.pdf) >> >>
<< /T (button3)/A << /S /GoToR /D [1 /XYZ 0 396 2]/F (../../pdf2.pdf) >> >>
<< /T (button4)/A << /S /GoToR /D [1 /Fit]/F (../../dir3/dir4/pdf2.pdf) >> >>
<< /T (button5)/A << /S /GoToR /D [1 /FitH -32768]/F (dir3/pdf2.pdf) >> >>
<< /T (button6)/A << /S /GoToR /D [1 /FitV 0]/F (/D/DIR4/DIR5/PDF2.PDF) >> >>
<< /T (button7)/A << /S /GoToR /D [1 /FitB]/F (/PC1/DIR6/PDF2.PDF) >> >>
/Root 1 0 R
The first five and the last nine lines of the file comprise what I call a skeleton FDF.
They are the starting point for building an FDF file that can be used to modify field
attributes. Simply copy these lines into a text editor and modify to suit your needs. The
seven lines in the middle that begin with << /T specify the field names and the action
dictionaries. You may include as many of these lines as is required. The value of the
T key is the name of the form field and the value of the
A key contains the required elements for the action. When this
file is imported into a form (e.g., File > Import > Form Data), all form fields in the PDF
that match the names in the FDF will be assigned a Mouse
Up action of Go to View. Any actions that are
currently assigned to the Mouse Up event will be
replaced by the one specified in the FDF file.
FDF files can be used for much more than just importing and exporting form data. They
make it possible to automate changes to forms, access features that are normally
unavailable, change field properties on-the-fly, create enhanced form fields, and access
undocumented features. I will present more information on some other useful applications of
FDF in future articles. In the mean time, sit down with a copy of the PDF Reference Manual
and the FDF Toolkit documentation to see what interesting things you can come up with.
I’d like to thank Dr. D. P. Story for (unwittingly) providing much of the inspiration for
my investigation into the technique presented here. His pioneering work (2) into using pdfmarks to create and enhance PDF forms should be read by everyone who wants to gain a deeper understanding of forms and other aspects of PDF.
- FDF Toolkit Overview, Technical Note #5194, Adobe Systems Incorporated, November 10,
1999. FDF Toolkit Reference, Technical Note #5193, Adobe Systems Incorporated, November 10,