PDF In-Depth

Linking Up with FDF

February 18, 2000

Advertisement
Advertisement
 

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:\DIR1\DIR2\PDF1.PDF C:\DIR1\DIR2\PDF2.PDF PDF2.PDF
C:\DIR1\DIR2\PDF1.PDF C:\DIR1\PDF2.PDF ../PDF2.PDF
C:\DIR1\DIR2\PDF1.PDF C:\PDF2.PDF ../../PDF2.PDF
C:\DIR1\DIR2\PDF1.PDF C:\DIR1\DIR2\DIR3\PDF2.PDF DIR3/PDF2.PDF
C:\DIR1\DIR2\PDF1.PDF C:\DIR3\DIR4\PDF2.PDF ../../DIR3/DIR4/PDF2.PDF
C:\DIR1\DIR2\PDF1.PDF D:\DIR4\DIR5\PDF2.PDF /D/DIR4/DIR5/PDF2.PDF
C:\DIR1\DIR2\PDF1.PDF \\PC1\DIR6\PDF2.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. http://partners.adobe.com/
  2. http://www.math.uakron.edu/~dpstory/acrotex.html
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.