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.

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

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.

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.

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.

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)

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.

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)

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.

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.