Linking Up with FDF

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
recommended reading.)

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
face to display a graphic, and use JavaScript to programmatically show/hide a button. Also,
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
GoToR action:

>Key

>Description

/S Subtype, always GoToR
/D Destination in target

file

/F File specification of target

PDF

/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.

>Destination

>Description

/D (Section

8)

Link to named destination

‘Section 8’

/D [ 20 /XYZ null

null null ]

Link to page 21, retain

(inherit) view

/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:

>Source

PDF

>Target

PDF

>File

specification

C:DIR1DIR2PDF1.PDF

C:DIR1DIR2PDF2.PDF PDF2.PDF

C:DIR1DIR2PDF1.PDF

C:DIR1PDF2.PDF ../PDF2.PDF

C:DIR1DIR2PDF1.PDF

C:PDF2.PDF ../../PDF2.PDF

C:DIR1DIR2PDF1.PDF

C:DIR1DIR2DIR3PDF2.PDF DIR3/PDF2.PDF

C:DIR1DIR2PDF1.PDF

C:DIR3DIR4PDF2.PDF

../../DIR3/DIR4/PDF2.PDF

C:DIR1DIR2PDF1.PDF

D:DIR4DIR5PDF2.PDF /D/DIR4/DIR5/PDF2.PDF

C:DIR1DIR2PDF1.PDF

\PC1DIR6PDF2.pdf

/PC1/DIR6/PDF2.PDF

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.


%FDF-1.2
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) >> >>
]
>>
>>
endobj
trailer
<<
/Root 1 0 R
>>
%%EOF

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.

Summary

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.

Acknowledgement

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.

References

  1. FDF Toolkit Overview, Technical Note #5194, Adobe Systems Incorporated, November 10,
    1999. FDF Toolkit Reference, Technical Note #5193, Adobe Systems Incorporated, November 10,
    1999. target=’_NEW’>http://partners.adobe.com/
  2. target=’_NEW’>http://www.math.uakron.edu/~dpstory/acrotex.html

You May Also Like

About the Author: George Johnson

Leave a Reply