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

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.

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

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

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 www.adobe.com.