Form Data Format Files
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.
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 |
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:
- Initialize the FDF Toolkit library.
Only required explicitly under Unix with C/C++. - Create the FDF Data.
FDFCreate (“new” in Perl). - Add a template to the file.
FDFAddTemplate (“AddTemplate” in Perl). - Set the values for the fields in the template.
Loop through Step 4 until you have all the values set for the page. - Loop through Step 3 to 4 until you have built your entire file.
- Save the FDF Data
- 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.
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:
- Creates a new FDF stream.
- Reads the address data from addresses.txt.
- Splits the tab-delimited address data.
- Adds a page for the first 30 names.
- Sets values for the first 30 names.
- Repeats steps 4 and 5 until it reaches the end of the data.
- 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:
- Make sure you have Perl 5.6 and Adobe’s FDFToolkit for Perl installed.
- 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. - Enter the following command
$Perl labels.pl
and press Return (or Enter). - 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.