FDFMerge and FDFMerge Lite – Form Data Format (FDF)

In this chapter…

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

Creating an FDF File

An FDF file is a plain text file that contains a list of form fields and their values. Although we’ll show you how to create one by hand, most often FDF files are software generated. These are some of the more common methods to create FDF files:

  • Use Adobe Acrobat to export forms data directly to a file.
  • Use a Submit Form action in Acrobat’s Field Properties pop-up to export FDF data to a web server.
  • Export data from a database and save it as an FDF file, using a script that you create.
  • Write a program that will build an FDF file as a plain text file, using a script that you create.
  • Use Adobe’s FDF Toolkit, see FDF resources for more information.

The FDF file format

An FDF file has the following format:

  • An FDF file must begin with %FDF and end with %%EOF.
  • The data is given as name-value pairs, enclosed in double angle brackets: << >>:
    /T indicates form field name
    /V indicates form field value

In this section we’ll use the sample file: samples/testfiles/testfile.fdf as an example. Within it are six name-value pairs. The lines before and after these pairs are identification and formatting information.

%FDF-1.2
%âãÏÓ
1 0 obj
<<
/FDF << /Fields [
<< /T (CheckBox1) /V /Yes>>
<< /T (CheckBox2) /V /Off>>
<< /T (ComboBox) /V (6)>>
<< /T (ListBox) /V (fontsize)>>
<< /T (Basefont) 
/V (This is a Multi-line text box. Note that the text wraps around to the next line!)>>
] >> 
/ID[<B5B9EA85E3E2A7372D233185314E367E><7CA8657022DA815A340A57D516E030DC>
] >> 
>> 
endobj
trailer
<<
/Root 1 0 R
>>
%%EOF

Note: If you double-click on an FDF file, Acrobat will try to find its accompanying PDF file. If you want to see the contents of an FDF file open it in a text editor.

Line breaks and new lines in FDF files

When long character strings are used in text fields, you may need to manually insert line breaks, so that the text wraps in the form field the way you would like it to. If you put a line break in a field value, you need to adjust the spaces between words.

Inserting line breaks in FDF files, \r and \n

In order to make a multi-line text field format the way you want it to, you may have to add newline characters, using \r or \n. They both work the same way. A single new line results from any of the following: \r, \n, or \r\n. For example, if your text is:

Among these are time management

and you would like it to look like:

Among these are
time management

enter this into the FDF value for the form field:

Among these are\rtime management

Using the line continuation character \

The value of a name-value pair should be on a single line. If you need to break a value onto the next line, use the \ line continuation character.

Entering the following into the FDF value for the form field:

Among these \
are time man\
agement

Will look like this in the output PDF:

Among these are time management

Using special characters

Special characters can be entered directly into the FDF file, or they can be represented by octal characters. An octal character is represented by a \ followed by a three digit octal code. FDFMerge Lite and FDFMerge use octal codes with PDF encoding. A list of octal codes can be found in Appendix D of the PDF Reference manual on Adobe’s website.

Entering the following into the FDF value for the form field:

\200 Among these are time management

Will look like:

• Among these are time management

FDF resources

For more information about FDF, refer to Adobe for the following resources:

  • The FDF Toolkit. Adobe provides this free API (Application Program Interface) for writing a server application that generates FDF data, or to parse FDF data from a form.
  • The PDF Reference Manual provides useful FDF documentation.
  • Be sure to check the FDFMerge Lite or FDFMerge pages of the Appligent website.

Creating an XFDF File

XFDF is an XML version of an FDF file. You can create XFDF files the following ways:

  • Use Adobe Acrobat to export forms data directly to a file.
  • Export data from a database and save it as an XFDF file, via a script that you create.
  • Write a program that will build an XFDF file as a plain text file, via a script that you create.
  • Use the Submit Form action in Acrobat’s Field Properties pop-up to export XFDF data to a web server.

You cannot use the FDF Toolkit to create XFDF files.

XML is a structured language that begins with the XML file itself as the topmost object. XFDF files have an element called fields that contain field and value.

Basic XFDF file structure

The table below shows the basic XFDF file structure.

Element Attribute Content
<XFDF> Topmost element
<fields> All the field values for this template
<field (T)> name Field name
<value (V)> value Field value


Refer to the XML Forms Data Format Specification on the Adobe website for more information about XFDF files. You can go to https://www.immagic.com/eLibrary/ARCHIVES/TECH/ADOBE/A070914X.pdf to download the specification.

An example of an XFDF file which shows this simple structure follows. The sample FDF form data would look like this in XFDF:

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
   <fields>
      <field name="CheckBox1">
      <value>A</value>
      </field>
      <field name="CheckBox2">
      <value>Off</value>
      </field>
      <field name="CheckBox3">
      <value>Off</value>
      </field>
      <field name="ComboBox1">
      <value>Option 1</value>
      </field>
      <field name="ListBox1">
      <value>Item2</value>
      </field>
      <field name="MultiLineText1">
      <value>This is a Multi-line text box. Note that the text wraps around to the next line!</value>
      </field>
      <field name="RadioGroup1">
      <value>Yes</value>
      </field>
      <field name="TextBox1">
      <value>Sample Text</value>
      </field>
   </fields>
</xfdf>

Line breaks and new lines in XFDF files

To manually insert a line break in form field text, type a carriage return directly into the value in the XFDF file. You do not need to use /r or /n characters. Make sure to check Multi-line on the Options tab of the Text Field Properties dialog in Acrobat.

Using Unicode

FDFMerge Lite and FDFMerge can use Unicode to place Asian language characters in a text form field. The only place double-byte characters can be used is in the value parameter of a text form field.

Note: You must use an XFDF file to use Unicode. FDFMerge Lite and FDFMerge do not support Unicode in FDF files.

Prerequisites for Acrobat full version

In order to use Acrobat to view and print Asian text, you must have Asian language support files installed for both the Operating System (OS) and Acrobat. The table below shows whether Asian font support is automatically installed for your combination of OS and Acrobat, or whether you have to manually install it.

Unicode font support

OS Font Support
Version Automatic Manual
OS Windows 7 & higher
Mac OS X
Acrobat Windows X and higher
Mac OS X 10.0 and higher

Operating system

Asian font support is automatically installed for all OS platforms except Windows 2000/NT. To install Asian font support, open Regional Options in the Control Panel, and add the fonts you want. You may need your original installation disk. Refer to the Windows on-line help for more information. You can also install keyboard support.

Acrobat

Asian font support is automatically installed only in Acrobat 6 under Mac OS X. For all other versions, you will need to do a custom installation, and choose to install Asian font support. Refer to the Acrobat on-line help for more information.

Prerequisites for Acrobat Reader

In order to use Acrobat Reader to view and print Asian text, you must install the Asian Font Pack from Adobe.

Windows/UNIX

Download and install the Asian Font Pack.

Reader components can be updated in a variety of ways. Some updates are available when you open a PDF that triggers the updating process automatically. For example, if you open a form that uses Asian language fonts, Reader asks whether you want to download the fonts. Other updates are available only from the Help menu, and you must install them manually. Some updates are available both automatically and manually.

Mac OS X

You cannot download the Asian Font Pack for Mac OS X. You must choose to install it when you install Acrobat Reader. If you did not, you must reinstall Reader.

Available fonts

There are standard Adobe fonts that are available when using Unicode characters. The table below lists the seven fonts that are available for double-byte character stamping:

Double-byte character fonts

Font Name in FDFMerge
and FDFMerge Lite
Font name in Adobe Acrobat
HeiseiKakuGo-W5 Heisei Kakugo
HeiseiMin-W3 Heisei Mincho
HYGoThic-Medium HYGoThic Medium
HYSMyeongJo-Medium HYSMyeongJo Medium
MHei-Medium MHei-Medium
MSung-Light MSung Light
STSong-Light STSong Light

Use the font name in the left-hand column above in the Font parameter in your FDF, XFDF or FormInfo file.

Character encodings

Create UTF encoded XFDF files with a text editor that supports UTF-8.

UTF-8

Type double-byte Unicode characters directly into the XFDF file using any text editor which supports UTF-8. Your system must have the appropriate fonts installed. For example:

value for CJK characters

Only the value field can have Asian fonts or any other higher level Unicode character. All other fields must use only the Latin character set (the first 128 characters, equivalent to “ASCII”).

Note: UTF-8 encoded characters are converted to UTF-16 before being placed into the form field. UTF-16 characters are placed directly into the document with no intervention by FDFMerge Lite or FDFMerge. If you want to make sure your characters are placed directly with no conversion, use UTF-16.

UTF-16

UTF-16 requires the double-byte characters in big-endian hexadecimal. Each character is represented by &#x and the four digit code for the character, followed by a semi-colon (;). Enter the entire Text parameter as a string of hex codes with no breaks. For example:

For example, to enter the three characters 5185 5BC6 306E, enter:

&#x5185 ; &#x5BC6 ; &#x306E ;

Refer to Unicode resources for help finding codes.

Multi-line UTF-8/UTF-16 stamps

In order to get multi-line text fields, you must make sure to check “Multi-line” in the Options tab of the Text Field Properties dialog. Then, either:

  • For UTF8, enter a newline character directly by typing a carriage return. For example:

multiline CJK characters

  • For UTF16, place the newline character (below) directly into the text string.
    
&#x2028 ;
    For example:

Shows new line character

Both values result in this field value:

CJK characters displayed in form field

Text containing double-byte characters will not automatically wrap.

Unicode resources

  1. The Unicode Consortium has the complete Unicode specification, providing a wealth of information on Unicode, character sets, and conversions.
  2. SC UniPad provides a free trial of UniPad, a Windows-based Unicode text editor.
  3. IT and communication provides an extensive tutorial on character sets, including Unicode.

Notes on JavaScript and Formatting Fields

Using JavaScript in PDF forms

FDFMerge Lite and FDFMerge do not have the capability to calculate form fields. If you use JavaScript in your PDF forms to calculate fields, the value in the FDF file is what will appear in the flattened output PDF file. Therefore, you need to have the correct field value present in the form or in the FDF file prior to merging.

If you will be merging and not flattening your form fields you can add a JavaScript to your form that will perform all calculations when the file is opened. However, you will get a warning from Adobe Acrobat to save the file when it is closed.

Formatting form fields

If you are flattening your form fields and you have set one or more fields as formatted, for example, as currency, then you will need to include the formatting for that value in the FDF file. For example, if you wish the value of a field to be $1,234.00 in the output PDF file, then the value in your FDF file needs to be /V ($1,234.00). If you put the value into the FDF as “1234” it will appear in the flattened PDF document as “1234.”

This behavior will sometimes also be true for non-flattened forms, when the form fields are still active. After merging the formatting settings may not appear to have “taken.” However, if the value in the field is modified (by adding and/or removing a character), formatting settings will take effect and format the value correctly to the settings. Therefore, whether merging and flattening or only merging, it is good practice to format the field as you would like it to appear directly within the FDF file.

Note: If you choose not to flatten form fields but just merge them, you can run with the -norebuild option and allow Acrobat to build the appearances for you. Running with the -norebuild flag would allow Acrobat to perform the calculations setup in form fields.

Using PDF images in button fields

Using an FDF file, FDFMerge Lite or FDFMerge can merge the first page of a PDF document onto a button field. You must specify the value of a button to be a PDF filename in the FDF file. The button will remain active after merging with FDFMerge Lite or FDFMerge. For example:

/T (ThisButton) /V (C:\FDFMerge\ThisPDFfile.pdf)

This technique may also be used to stamp the first page of a PDF document onto a button if -s is specified.

Merging a PDF onto a button is different from stamping a PDF, JPEG or TIF onto a form field. When an image is stamped onto a button, the action of the button is lost in the form flattening. Active buttons appear on flattened documents if:

  • A PDF file path is set in the FDF file for the fieldname,
  • The button has had an icon set.

Buttons which contain nothing but text (Label only) will not be stamped. This feature only works on buttons containing PDF Images.