In this chapter… 

……we explain Forms Data Format (FDF) files: what they look like, how to generate them, and tips for using them.

• Form Data Format files explains what they are, and what they look like.
• The FDF Toolkit explains how to use Adobe’s FDF Toolkit to generate FDF files, and provides examples.
• Merging PDF pages onto buttons shows how to merge a PDF file onto a button form field.
• Examples provide examples for using FDFToolkit to create an FDF file.

Form Data Format files

A Form Data Format file is a text file that contains a list of form fields and their values. FDFMerge Pro uses the data in FDF files to assemble and fill out forms. There are two kinds of FDF files:

• Classic—supplies data to fill out an existing form.
• Template-based—directs the construction of a new PDF document based on the templates found inside specified PDF files, and supplies the data to fill out the form(s) in the new document.

If you have used Appligent’s FDFMerge, you are familiar with classic FDF files. The FDFMerge Pro User Guide takes you through building one by hand. Template-based FDF files are more complex, and although we will be showing examples below, we do not recommend that you try to build them by hand. Use Adobe’s FDF Toolkit, available free on their website. See The FDF Toolkit for more information.

Form Data Format structure

The FDF file specification structures FDF files in terms of objects. Objects are enclosed in double angle brackets: << >>. The objects of importance to us are:

• Array objects—collections of other objects, including dictionaries and other arrays. The content of the array object is enclosed in square brackets: <</array [contents]>>.
• Dictionary objects—collections of key/value pairs. Values can be any kind of object, including an array or another dictionary. The dictionary contents are enclosed in double angle brackets: <</dictionary << /key /value >> >>.

The following table shows the basic FDF file structure:

Object	Type	Content
FDF	dictionary	Topmost object
Pages	array	Descriptions of every page of the new file
Template	array	Starts a new page
Tref	dictionary	Reference to a template for the page
Fields	array	All the field values for this template
key (T)	Name	Field name
value (V)	Value	Field value
Additional Templates structured as above	array	Starts the next page

Object	Type	Content
FDF	dictionary	Topmost object
Pages	array	Descriptions of every page of the new file
Templates	array	Starts a new page
Tref	dictionary	Reference to a template for the page
Fields	array	All the field values for this template
key (T)	Name	Field name
value (V)	Value	Field value
Templates	array	Starts the next page

Notes

The page/template relationship

Each page uses one template. Each template creates a new page.

Spawning new pages

If there is more data than can fit on one page, create a new page using the same template, and continue to populate the fields on the new page.

Comments

You can add comments to the FDF file using the percent sign (%).

Example

The following example shows the FDF template file, template.txt, in the samples folder. You can create a simple FDF file by copying the sections marked to add pages and fields.

%FDF-1.2	FDF file
1 0 obj	FDF Object
<< /FDF	FDF dictionary
<< /Pages [	Pages array
%page – copy to end_page to add pages	Copy this section to add pages
<< /Templates [	Templates array object – start of page
<< /TRef	TRef dictionary – first template
<< /F (/path/PDFFormName.pdf)	template file – PDFFormName.pdf
/Name (TemplateName)	Template page name – TemplateName
/Rename /false >>	Do not rename fields – FDFMerge Pro will do it
/Fields [	Fields array
%fields – copy to end_field to add fields	Copy this section to add fields
<< /T (FieldName)/V (FieldValue)>>	First field dictionary with Name and Value
%end_field
] >>	End TRef dictionary
] >>	End Templates object – end of page
%end_page
] >>	End Pages object
>>	End FDF dictionary
endobj	End FDF Object
trailer
<< /Root 1 0 R >>
%%EOF	End of File

The FDF Toolkit

The FDF Toolkit is an API that allows you to write server side applications to generate FDF files. The FDF Toolkit has support for COM on Windows, C and Perl for Windows, Solaris, AIX or Linux, or Java for all 1.2 or higher compatible Virtual Machines.

To get the FDF Toolkit, visit http://www.adobe.com and search for “FDF Toolkit.”

Generating a template-based FDF file

The actual process to generate an FDF file varies depending on which platform and coding language you are using, but the general process goes like this:

1. Initialize the FDF Toolkit library.
   Only required explicitly under Unix with C/C++.
2. Create the FDF Data.
   FDFCreate (“new” in Perl).
3. Add a template to the file.
   FDFAddTemplate (“AddTemplate” in Perl).
4. Set the values for the fields in the template.
   Loop through Step 4 until you have all the values set for the page.
5. Loop through Step 3 to 4 until you have built your entire file.
6. Save the FDF Data
7. Close the FDF Data buffers and free any resources used.

Refer to the FDF Toolkit Overview and Reference for detailed information on each step, and Examples below for using the FDFToolkit.

Notes

FDFAddTemplate

Always set bNewPage to true. FDFMerge Pro will not accept more than one template per page.

FDFMerge Pro ignores the value of bRename. It is always assumed false. FDFMerge Pro will rename the fields itself.

Merging PDF pages onto buttons

FDFMerge Pro can merge a PDF document page onto a button field. Use the Appearance Reference (APRef) object as the value of the field. Buttons with PDF pages merged onto them remain active buttons.

Using the APRef object

The APRef object takes one parameter, /N (Normal) which specifies the file and page to use. It looks like this:

/APRef << /N <</F (file name) /Name (page name)>> >>

/Name (page name) is optional. If you do not specify it, FDFMerge Pro will merge the first page of the file onto the button.

To merge the first page of the file ButtonFile.pdf onto a button called Submit, place this field specification in the Fields array of your FDF file:

<<
/T (Submit)
/APRef
<</N
<</F (ButtonFile.pdf) >>
>>
>>

Using FDFToolkit

To merge a PDF file onto a button using the FDFToolkit, use the FDFSetAPRef call (SetAPRef in Perl) to create an APRef object.

Notes

Always set whichFace to FDFNormalAP. FDFMerge Pro will not set Rollover or Down values.

Examples

Address labels sample

We’ve included a sample application that fills out address labels from the names and addresses in a database. In the samples/labels directory, you’ll find:

• addresses.txt — a tab-delimited text file “database” of 60 sample names and addresses.
• labels.pl — a perl script using the FDFToolkit to generate an FDF file.
• labels.fdf — an FDF file produces by the labels.pl perl script.
• labels.pdf — a PDF file with one template page of 30 labels, designed to match commercially available mailing labels.

In this chapter you’ll use the labels.pl script to create mylabels.fdf.

The script

The script labels.pl does the following:

1. Creates a new FDF stream.
2. Reads the address data from addresses.txt.
3. Splits the tab-delimited address data.
4. Adds a page for the first 30 names.
5. Sets values for the first 30 names.
6. Repeats steps 4 and 5 until it reaches the end of the data.
7. Writes the output FDF file.

Here is the Perl script:

#!/usr/bin/perl 
use Acrobat::FDF;

# Create a new FDF Stream
$outFDF = new Acrobat::FDF;

# Read the address data
open (ADDRESSES,’./samples/labels/addresses.txt’);
@Addresses = <ADDRESSES>;
close (ADDRESSES);

# Set up for pagination: 30 labels per page
$page = -1;
$i = 1;

# Split the tab-delimited text file
foreach  $Addresses (@Addresses) {
chomp($Addresses);
($FirstName,$LastName,$Street,$City,$ST,$Zip) =
split(/\t/,$Addresses);

# test whether to start a new page
if ($i % 30 == 1) {
$outFDF -> AddTemplate
(true,”./samples/labels/labels.pdf”,”Addresses”,false);
$page++ }

# Normalize the data: Field names are always 1-30
$I = $i – 30 * $page;

# Set the values for this page
$outFDF -> SetValue (“Name_$I”, “$FirstName $LastName”, false);
$outFDF -> SetValue (“Address_$I”, “$Street”, false);
$outFDF -> SetValue (“CityState_$I”, “$City, $ST $Zip”, false);
$i++
}

#When finished, write FDF file
$filename = “./samples/labels/mylabels.fdf”;
$outFDF -> Save ($filename);

Running the script

To run the script manually:

1. Make sure you have Perl 5.6 and Adobe’s FDFToolkit for Perl installed.
2. Change the working directory to the FDFMerge Pro /samples directory.
   The default location for the FDFMerge Pro samples directory in Windows is
   C:\Appligent\FDFMergePro\samples\.
   On other platforms, it will be wherever you installed FDFMerge Pro.
3. Enter the following command
   $Perl labels.pl
   and press Return (or Enter).
4. Examine mylabels.fdf and compare to the sample shown below.

The output

The resulting FDF file looks like this. This sample only shows one address per page for clarity.

%FDF-1.2
%‚„oe”
1 0 obj<</Version/1.3/FDF<</Pages 2 0 R>>>>
endobj
2 0 obj[<</Templates 3 0 R>><</Templates 5 0 R>>]
endobj
3 0 obj[<</Fields 4 0 R/Rename
false/TRef<</F<</F(./samples/labels/labels.pdf)/V
true>>/Name(Addresses)>>>>]
endobj
4 0 obj[<</T(Name_1)/V(Sara Adams)>><</T(Address_1)/V(9150
Kiefer St.)>><</T(CityState_1)/V(Aberdeen, SD 57401)>>...]
endobj
5 0 obj[<</Fields 6 0 R/Rename
false/TRef<</F<</F(./samples/labels/labels.pdf)/V
true>>/Name(Addresses)>>>>]
endobj
6 0 obj[<</T(Name_1)/V(Dorothy Hughes)>><</T(Address_1)/V(2500
Coakley Court)>><</T(CityState_1)/V(Washington, DC 20001)>>...]
endobj
trailer
<</Root 1 0 R>>
%%EOF