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: Most of the functionality described on this page is available for FDFMerge only.
The following sections provide the details:
- When To Use FormInfo Files
- Constructing a FormInfo File
- The Header Block
- Header Block Parameters
- Sample Header Block
- Field Entry Parameters
- Which Settings FDFMerge Listens to First
- Using PDF Images in button fields
When To Use FormInfo Files — FDFMerge only
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 — FDFMerge only
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 — FDFMerge only
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 — FDFMerge only
The FormInfo file always begins with the Header Block.
Specifying default properties with the Header Block — FDFMerge only
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 — FDFMerge only
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 — FDFMerge only
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 — FDFMerge only
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 — FDFMerge only
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 — FDFMerge only
FieldName (required) — FDFMerge only
The name you gave to the field when creating your form, or the name of the field in an FDF document.
FontName (optional) — FDFMerge only
The name of the font to use.
There are two types of fonts FDFMerge can use:
- Base 14 fonts. FDFMerge can supply these fonts:
| • Courier | • Helvetica |
| • Courier-Bold | • Helvetica-Bold |
| • Courier-Oblique | • Helvetica-Oblique |
| • Courier-BoldOblique | • Helvetica-BoldOblique |
| • Times Roman | • Symbol |
| • Times Bold | • Zapf Dingbats |
| • Times Italic | |
| • Times Bold Italic |
- PostScript Type 1 fonts. PostScript Type 1 fonts may be purchased from Linotype's website or Adobe's website.
- If you use a Type 1 font, specify the PostScript name of the font, making sure to use the correct spelling, capitalization, and hyphenation (refer to the documentation that came with the font). For example, the PostScript name for New Century Schoolbook is NewCenturySchlbk; for News Gothic it's NewsGothic. You cannot use TrueType or OpenType fonts. If you use a font other than a system or Standard font, it must be a PostScript Type 1 font.
FontFile (optional) — FDFMerge only
If you specify a Type 1 PostScript font, you must 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 is a conflict between Font and FontFile, the information in the font file overrides the font name.
Note: If you use a PostScript Type 1 font more than once in your FormInfo file, the FontFile parameter is only required the first time. Specifying the same FontFile more than once may result in unexpectedly large documents.
FontSize (optional) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
Use ColorRed, ColorGreen, 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) — FDFMerge only
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 — FDFMerge only
The color space used is determined by the parameters you use to specify the color: Gray; 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 — FDFMerge only
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 — FDFMerge only
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% Red is 0.25 X 255 = 64. The values for CMYK must be in the range 0–1. If you find the colors defined as percentages, convert to decimal equivalent. For example, 52% Cyan is 0.52.
Justification (optional) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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) — FDFMerge only
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 — FDFMerge only
There are three ways for FDFMerge to get information about a form field to stamp information into a new file:
- From a Field Entry in the FormInfo file
- From the Header Block in the FormInfo file
- 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:
- 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.
- Header Block in FormInfo file. These attributes override values in the source PDF form, but field entries take precedence over header information.
- 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.
Using PDF images in button fields — Applies to both FDFMerge Lite and FDFMerge
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.