FormInfo Files

In this chapter…

…we describe how to use a FormInfo file to flatten and customize form fields. When to use FormInfo files and how to build them is explained in detail. We also describe how to stamp PDF pages and images into form fields using the FormInfo file.

Note: The functionality described on this page is available for FDFMerge only.

When To Use FormInfo Files

Use a FormInfo file with FDFMerge when you want to do one or more of the following:

  • Flatten only selected form fields
  • Change the original formatting in some or all of the fields being flattened
  • Stamp PDF pages and images into form fields

If you want to flatten all of the fields and retain the original formatting, you do not need a FormInfo file. Instead, merge the file with data using an FDF or XFDF file and use the -s command-line option to flatten all of the fields. See -s — Replace All Fields With Stamps for more information.

Constructing a FormInfo File

A FormInfo file allows you to specify the properties of some or all of the form fields in a PDF document. By setting default properties, you can specify properties for all fields at once, and fine tune individual fields as needed. You can specify the format of the text in a field, the border and background of the field, and an image or PDF file to stamp onto a field.

A FormInfo file can consist of three components:

  • Comments — for making notes
  • A Header Block — for setting default properties of all fields
  • Field Entries — for specifying fields to be flattened and/or modified

The following sections explain how to create these components.

Adding comments

Comments in your FormInfo file are lines of text that you don’t want to be read by FDFMerge. They have several useful functions:

  • Making notes, to describe the file and its components, and create reminders for further action
  • Testing and debugging, to deactivate or “comment out” parameters that may be causing problems

Comments start with the hash or number symbol (#) and must be placed at the beginning of a line:

#This is a comment in my parameter file.

The Header Block

The FormInfo file always begins with the Header Block.

Specifying default properties with the Header Block

The Header Block specifies the default properties for all the form fields in the document. For example, if you specify a point size and font name in the Header Block, they will apply to all form fields. You can override those values for individual fields with separate Field Entries; for more information, refer to Field Entry Parameters. The Header Block must begin with BeginHeader and needs to be placed before any Field Entries. EndHeader needs to be placed after the default parameters at the end of the Header Block.

The table Header Block Parameters lists all the Header Block parameters. They have the same syntax and meaning as the corresponding Field Entry parameters, except they specify default properties for all fields and begin with the word “Default.” For detailed parameter descriptions, refer to Field Entry Parameters.

To see how FDFMerge resolves conflicts when field attributes are specified in the PDF source file, as well as the Header Block and a Field Entry, see Which Settings FDFMerge Listens to First.

Header Block Parameters

The table below lists all of the Header Block parameters that are used in the FormInfo file.

Type Parameter Content
Begin BeginHeader Beginning of header block
Text DefaultFontName Name of font
DefaultFontFile Location of font file, if necessary
DefaultFontSize Size of font, in points
DefaultGray Grayscale color value for text color (0–100)
DefaultRed
DefaultGreen
DefaultBlue
RGB color values for text color (0–255)
DefaultCyan
DefaultMagenta
DefaultYellow
DefaultBlack
CMYK color values for text color (0–1)
DefaultJustification Text justification (Left, Center, or Right)
DefaultFontXScale Scale text characters horizontally (0–100)
DefaultFontYScale Scale text characters vertically (0–100)
DefaultCharSpace Adjust character spacing
DefaultWordSpace Adjust word spacing
DefaultTextLineSpace Adjust line spacing
DefaultCropToField Crop text to fit form field (Default: No)
Format DefaultBorderVisible Apply border
DefaultBorderGray Grayscale color value for border color (0–100)
DefaultBorderRed
DefaultBorderGreen
DefaultBorderBlue
RGB color values for border color
DefaultBorderCyan
DefaultBorderMagenta
DefaultBorderYellow
DefaultBorderBlack
CMYK color values for border color
DefaultBorderWidth Width of border in points (1, 2, or 3)
DefaultBackgroundVisible Apply background color
DefaultBackgroundGray Grayscale color value for background color (0–100)
DefaultBackgroundRed
DefaultBackgroundGreen
DefaultBackgroundBlue
RGB color values for form field background (0–255)
DefaultBackgroundCyan
DefaultBackgroundMagenta
DefaultBackgroundYellow
DefaultBackgroundBlack
CMYK color values for form field background (0–1)
End EndHeader End of header block

Sample Header Block

Enter parameters as follows:

parameter (value)

There must be at least one space between the parameter and the value.

A sample header, using the Type 1 font New Century Schoolbook, looks like this:

BeginHeader
DefaultFontName (NewCenturySchlbk-Roman)
DefaultFontFile (C:\Fonts\NewCenSchRom.pfb)
DefaultFontSize (12)
DefaultRed (255)
DefaultGreen (0)
DefaultBlue (0)
DefaultJustification (left) 
DefaultBorderVisible (Yes)
DefaultBorderRed (127)
DefaultBorderGreen (233)
DefaultBorderBlue (55)
DefaultBackgroundVisible (Yes)
DefaultBackgroundRed (60)
DefaultBackgroundGreen (200)
DefaultBackgroundBlue (0)
DefaultCropToField (Yes)
EndHeader

It is not necessary to provide default values for every parameter. If you only want to ensure that all type is of the same point size (for example, 10 points) your header would look like this:

BeginHeader
DefaultFontSize (10)
EndHeader

Another example of a simple header is one that crops the text in all text fields, list boxes, and combo boxes:

BeginHeader
DefaultCropToField (Yes)
EndHeader

Field Entry Parameters

Each Field Entry specifies a field to be flattened and optionally applies customized formatting to the field, overriding all other settings in the Header Block and in the PDF file. Each Field Entry in a FormInfo file must begin with the keyword BeginField, end with the keyword EndField, and specify the name of the field it references. The table below lists all Field Entry parameters.

Type Parameter Required Content
Begin BeginField Beginning of field entry
Name FieldName Name of the form field
Text FontName Name of font
FontFile Location of font file, if necessary
FontSize Size of font, in points
ColorGray Grayscale color value for text color (0–100)
ColorRed
ColorGreen
ColorBlue
RGB color values for text color (0–255)
ColorCyan
ColorMagenta
ColorYellow
ColorBlack
CMYK color values for text color (0–1)
Justification Text justification (Left, Center, Right)
FontXScale Scale text characters horizontally (0–100)
FontYScale Scale text characters vertically (0–100)
CharSpace Adjust character spacing
WordSpace Adjust word spacing
TextLineSpace Adjust line spacing
CropToField Crop text to fit form field (Default: No)
Format BorderVisible Apply border
BorderGray Grayscale color value for border color (0–100)
BorderRed
BorderGreen
BorderBlue
RGB color values for border color (0–255)
BorderCyan
BorderMagenta
BorderYellow
BorderBlack
CMYK color values for border color (0–1)
BorderWidth Width of border in points (1, 2, or 3)
BackgroundVisible Apply background color
BackgroundGray Grayscale color value for background color (0–100)
BackgroundRed
BackgroundGreen
BackgroundBlue
RGB color values for form field background if BackgroundVisible set to Yes (0–255)
BackgroundCyan
BackgroundMagenta
BackgroundYellow
BackgroundBlack
CMYK color values for form field background if BackgroundVisible set to Yes. (0–1)
Image Type Text, Image, or PDF (Default: Text)
ImageFileName Name of the image to use
PageNumber Page number, if Type is PDF
End EndField End of field entry

Simplest Field Entry

Enter parameters as follows:

parameter (value)

There must be at least one space between the parameter and the value.

The following shows the simplest Field Entry, one for flattening a field named Message:

BeginField
FieldName (Message)
EndField

A Field Entry that flattens and applies a border to the Message field looks like this:

BeginField
FieldName (Message)
BorderVisible (Yes)
EndField

Field Entry parameters defined

FieldName (required)

The name you gave to the field when creating your form, or the name of the field in an FDF document.

FontName (required as of version 7.0.2)

The name of the font to use.

Earlier versions of FDFMerge only supported Base 14 and Type 1 fonts.  FDFMerge 7.0.2 supports PostScript Type 1 fonts, True Type, Open Type and Base 14 fonts.

When specifying a font for FontName, be sure to use the correct spelling, capitalization, and hyphenation.  You can get a list of all the fonts that FDFMerge has access to by running fdfmerge -listfonts.  You need to enter the name of the font in the FontName parameter exactly how it appears in the list after running -listfonts.

FontFile (deprecated as of version 7.0.2)

This parameter was required in earlier versions of FDFMerge when specifying PostScript Type 1 fonts. With version 7.0.2, if the FontFile parameter is present in the FormInfo file, it will be ignored.

In earlied versions, if you specified a Type 1 PostScript font, you had to supply the path and name of the font file:

  • Fonts use two files, a .pfb and a .pfm file. Both files need to be in the same directory, but you specify the .pfb file.
  • If there was a conflict between FontName and FontFile, the information in the font file overrides the font name. Since FontFile is not longer being used,  the name of the font must appear in the FontName parameter as displayed after running -listfonts.

FontSize (optional)

Specifies the point size of the font that you are stamping into the form field. Fractional point sizes are allowed (for example, 11.5).

ColorGray (optional)

Use ColorGray if your color space is Grayscale. ColorGray specifies a shade of gray; use a value between 0 and 100, where 0 is black and 100 is white. A ColorGray of 15 would be a dark gray, and a ColorGray of 95 would be a very light gray.

ColorRed, ColorGreen, ColorBlue (optional)

Use ColorRedColorGreen, and ColorBlue if your color space is RGB. The values for these colors can be in the range of 0–255, where 0 represents none of the color and 255 represents 100% of the color. You can combine varying amounts of the three color components to generate virtually any color. Here are some examples:

To create purple text enter the following values for the color components:

ColorRed (102)
ColorGreen (51)
ColorBlue (204)

To create green text enter:

ColorRed (0)
ColorGreen (150)
ColorBlue (0)

Specifying a value of 150 for green will generate a medium shade. See Notes on color below for help choosing color values.

Note: You must include values for each color: ColorRed, ColorGreen, and ColorBlue. Use a setting of 0 for colors you do not want.

ColorCyan, ColorMagenta, ColorYellow, and ColorBlack (optional)

Use ColorCyan, ColorMagenta, ColorYellow, and ColorBlack if your color space is CMYK. The values for these colors can be in the range of 0–1, where 0 represents none of the color and 1 represents 100% of the color. You can combine varying amounts of the four color components to generate virtually any color. Here are some basic examples:

To create the same color purple text used in the RGB example, enter the following values for the color components:

ColorCyan (0.63)
ColorMagenta (0.76)
ColorYellow (0)
ColorBlack (0)

To create yellow text enter:

ColorCyan (0)
ColorMagenta (0)
ColorYellow (0.5)
ColorBlack (0)

Specifying a value of 0.5 for ColorYellow will generate a medium shade. See the Notes on Color below for help choosing color values.

Note: You must include values for each color: ColorCyan, ColorMagenta, ColorYellow, and ColorBlack. Use a setting of 0 for colors you do not want.

Notes on color

The color space used is determined by the parameters you use to specify the color: Gray; or Red, Green, Blue; or Cyan, Magenta, Yellow, Black. If you specify a color for a stamp in more than one color space, FDFMerge will use the last color specification.

Note: Use the same color space throughout the entire PDF document. Specifying different color spaces can yield unexpected results.

RGB vs. CMYK

If you’re not familiar with color spaces, you may be confused by the differences in the way colors are specified in RGB or CMYK.

RGB is a color space for televisions and computer monitors. Color is created by mixing Red, Green, and Blue light. The maximum values result in white light. Since computer monitors are digital, RGB levels are specified in a four-bit word, from 0 to 255.

CMYK is a color space for printing. Color is created by mixing Cyan, Magenta, Yellow, and Black inks. The maximum values result in black ink. Ink levels are specified in percentages, from 0 to 1.

How to select colors using RGB or CMYK components

Visibone Webmaster’s Color Lab has tools to help you select a color. When you select a color that you like, the code for that color is given in RGB (Red, Green, Blue), CMYK (Cyan, Magenta, Yellow, and blacK), and/or hexadecimal (used in HTML for web pages). Copy the RGB or CMYK values given and enter them into the corresponding parameters in the form info file. You may also have software already installed on your computer that will help you design colors by accepting different values for color and displaying the results.

  • Note: The values for RGB must be integers in the range 0–255. If you find colors defined as percentages, convert them to the 0–255 range. For example, 25 Cyan is 0.52.

Justification (optional)

Text alignment in the field. Possible values are:

  • Left, aligns text with the left margin of the form field
  • Right, aligns text with the right margin of the form field
  • Center, horizontally centers text between the left and right margins

FontXScale (optional)

Scale text characters horizontally (0–100). A value between 0.00 and 1.00 (0–100%) will scale down, numbers greater than 1.00 (>100%) will scale up.

FontYScale (optional)

Scale text characters vertically (0–100). A value between 0.00 and 1.00 (0–100%) will scale down, numbers greater than 1.00 (>100%) will scale up.

CharSpace (optional)

Adjust spacing in between characters. Positive values will increase the spacing, negative values will decrease the spacing. There is no “valid range”. Values less than -2 will start overlapping letters; values greater than 6 become hard to read.

WordSpace (optional)

Adjust spacing in between words. Positive values will increase the spacing, negative values will decrease the spacing. There is no “valid range”. Values less than -2 will start overlapping letters; values greater than 6 become hard to read

TextLineSpace (optional)

Adjust spacing in between lines. A value between 0.00 and 1.00 will decrease the line spacing, values greater than 1.00 will increase the line spacing. A line spacing of 0 will overlay lines on top of one another.

CropToField (optional)

Specifies whether to trim field text to fit the form field’s rectangle. CropToField applies to text fields, list boxes and combo boxes. If you will be using borders around your form fields, you will probably want to set CropToField to Yes.

BorderVisible (optional)

Specify Yes to create a border around a form field. Specifying No will create an invisible border. Specify the color as described below.

BorderGray (optional)

Use BorderGray if your color space is Grayscale. BorderGray specifies a shade of gray; use a value between 0 and 100, where 0 is black and 100 is white. A BorderGray of 15 would be a dark gray, and a BorderGray of 95 would be a very light gray.

BorderRed, BorderGreen, BorderBlue (optional)

Use BorderRed, BorderGreen, and BorderBlue to specify the border color if your colorspace is RGB. The values for these colors can be in the range of 0–255, where 0 represents none of the color and 255 represents 100% of the color. To specify a green border:

BorderRed (0)
BorderGreen (255)
BorderBlue (0)

Note: You must include values for each border color: BorderRed, BorderGreen, and BorderBlue. Use a setting of 0 for colors you do not want. Refer to ColorRed, ColorGreen, ColorBlue and Notes on color for more information about choosing colors.

BorderCyan, BorderMagenta, BorderYellow, And BorderBlack (optional)

Use BorderCyan, BorderMagenta, BorderYellow, and BorderBlack to specify the border color if your colorspace is CMYK. The values for these colors can be in the range of 0–1, where 0 represents none of the color and 1 represents 100% of the color. You can combine varying amounts of the four color components to generate virtually any color.

Note: You must include values for each border color: BorderCyan, BorderMagenta, BorderYellow and BorderBlack. Use a setting of 0 for colors you do not want. Refer to ColorCyan, ColorMagenta, ColorYellow, and ColorBlack and Notes on color for more information about choosing colors.

BorderWidth (optional)

BorderWidth is the width of the border you have defined, in points. The width of the border can be 1, 2, or 3 points. BorderWidth (1) is the narrowest, and BorderWidth (3) is the widest.

BackgroundVisible (optional)

Specify Yes to set a visible background for the form field. No will set an invisible background. Specify the color as described below.

BackgroundGray (optional)

Use BackgroundGray if your color space is Grayscale. BackgroundGray specifies a shade of gray; use a value between 0 and 100, where 0 is black and 100 is white. A BackgroundGray of 15 would be a dark gray, and a BackgroundGray of 95 would be a very light gray.

BackgroundRed, BackgroundGreen, BackgroundBlue (optional)

Use BackgroundRed, BackgroundGreen, and BackgroundBlue to specify the background color if your colorspace is RGB. The values for these colors can be in the range of 0–255, where 0 represents none of the color and 255 represents 100% of the color. To specify a green background:

BackgroundRed (0)
BackgroundGreen (255)
BackgroundBlue (0)

Note: You must include values for each background color: BackgroundRed, BackgroundGreen, and BackgroundBlue. Use a setting of 0 for colors you do not want. Refer to ColorRed, ColorGreen, ColorBlue and Notes on color for more information about choosing colors.

BackgroundCyan, BackgroundMagenta, BackgroundYellow, and BackgroundBlack (optional)

Use BackgroundCyan, BackgroundMagenta, BackgroundYellow, and BackgroundBlack to specify the background color if your colorspace is CMYK. The values for these colors can be in the range of 0–1, where 0 represents none of the color and 1 represents 100% of the color. You can combine varying amounts of the four color components to generate virtually any color.

Note: You must include values for each background color: BackgroundCyan, BackgroundMagenta, BackgroundYellow, and BackgroundBlack. Use a setting of 0 for colors you do not want. Refer to ColorCyan, ColorMagenta, ColorYellow, and ColorBlack and Notes on color for more information about choosing colors.

Type (required if stamping an Image or PDF)

Specifies the type of stamp for the form field: Text, Image, or PDF. Required if a JPEG, TIF or PDF file is specified for stamping into a form field. Use the keyword Image for a JPEG or TIF image; for a PDF document, use keyword PDF.

ImageFileName (required with Type Image or PDF)

Specifies the name of the JPEG, TIF or PDF file for stamping images into the specified form field. This name should be the full path name to the file.

The ImageFileName parameter is ignored when Type is set to Text.

PageNumber (optional with Type PDF)

Specifies which page from the PDF file to stamp into the form field. For example, to stamp the second page of a document into a button field, you would specify PageNumber (2).

The PageNumber parameter is ignored when Type is not set to PDF.

Which Settings FDFMerge Listens to First

There are three ways for FDFMerge to get information about a form field to stamp information into a new file:

  1. From a Field Entry in the FormInfo file
  2. From the Header Block in the FormInfo file
  3. From the original PDF form; whatever settings are there for font style, size, etc. can be used for stamping by FDFMerge

But what if the FontName, for example, is listed in two or more places for one form field, which value will FDFMerge take? The precedence order in FDFMerge is as follows:

  1. Form Field Entry in FormInfo file. Whatever is specified here is the final word. If FontName is Times here but Helvetica everywhere else, the text will be printed as Times.
  2. Header Block in FormInfo file. These attributes override values in the source PDF form, but field entries take precedence over header information.
  3. Source PDF form field attributes. If a form field does not have attributes specified in either a Field Entry or the Header Block of a FormInfo file, FDFMerge uses the attributes in the original PDF form file. If only some of the attributes are listed in a field entry or header, the remaining attributes are taken from the PDF source.