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

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.

Note: Since xFDF does not support templates, you cannot use xFDF with FDFMerge Pro.

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

FDF file structure

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


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.


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


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 TRef dictionary
] >> End Templates object – end of page
] >> End Pages object
>> End FDF dictionary
endobj End FDF Object
<< /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 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.



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.

Note: FDFMerge Pro does not support the /R (rollover) and /D (down) switches for APRef.

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


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


Address labels sample

Important! This example script is designed to clearly show how to use the FDFToolkit to create an FDF file. It does not contain adequate error checking. Do not use this script in a production environment.

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.
  •—a perl script using the FDFToolkit to generate an FDF file.
  • labels.fdf—an FDF file produces by the 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 script to create mylabels.fdf.

The script

The script 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:

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) {
($FirstName,$LastName,$Street,$City,$ST,$Zip) =

# test whether to start a new page
if ($i % 30 == 1) {
$outFDF -> AddTemplate
$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);

#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
    On other platforms, it will be wherever you installed FDFMerge Pro.
  3. Enter the following command
    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.

1 0 obj<</Version/1.3/FDF<</Pages 2 0 R>>>>
2 0 obj[<</Templates 3 0 R>><</Templates 5 0 R>>]
3 0 obj[<</Fields 4 0 R/Rename
4 0 obj[<</T(Name_1)/V(Sara Adams)>><</T(Address_1)/V(9150
Kiefer St.)>><</T(CityState_1)/V(Aberdeen, SD 57401)>>...]
5 0 obj[<</Fields 6 0 R/Rename
6 0 obj[<</T(Name_1)/V(Dorothy Hughes)>><</T(Address_1)/V(2500
Coakley Court)>><</T(CityState_1)/V(Washington, DC 20001)>>...]
<</Root 1 0 R>>

Note: The FDF file produced by FDFToolkit uses indirect objects to group form data. An explanation of this is beyond the scope of this manual. For more information, refer to the PDF Reference at