11.2 ⁑Electronic PDF Forms

The previous section just considered a PDF form that could be filled in using custom commands within the document. This section looks at creating a PDF form where a user can fill the form in using interactive buttons and text fields in a PDF viewer that supports forms, such as Adobe Reader.

The hyperref package [69] provides commands to generate an electronic PDF form. There's also the eforms package [91], which is part of the AcroTeX bundle, however this is only in MiKTeX and not in TeX Live. This section will look at using the hyperref package, since it's available in both MiKTeX and TeX Live.

The commands that generate the interactive elements of the form, must all be placed inside the Form environment.

\begin {Form}[⟨parameters⟩]
⟨form body⟩
\end {Form}

The optional argument ⟨parameters⟩ is a key=value list of options if a “submit” button is included in the form. Available options are:

action: The value should be the URL to process the form data.
encoding: The encoding of the URL. The norm is PDF-encoding. The only valid value for this option is html.
method: Values can be post or get.

The interactive elements can be created within the Form environment using any of the following commands:

\TextField [⟨options⟩]{⟨label⟩}

to create a text field;

\CheckBox [⟨options⟩]{⟨label⟩}

to create a check box;

\ChoiceMenu [⟨options⟩]{⟨label⟩}{⟨choices⟩}

to create a selection of choices, such as a list menu, a popup menu, a combo menu or a group of radio buttons, where ⟨choices⟩ is a comma-separated list of labels for each available choice or a key=value list of ⟨label⟩=⟨name⟩ options;

\PushButton [⟨options⟩]{⟨label⟩}

to create a push button;

\Submit [⟨options⟩]{⟨label⟩}

to create a submit button and

\Reset [⟨options⟩]{⟨label⟩}

to create a reset button.

In each case, the field has a textual label (given by ⟨label⟩) and a key=value list of options. There are a large number of options available. For the full list, see the hyperref manual [69]. A selection of common options follows:

accesskey: Specifies the shortcut key to activate/focus an element. There is no default value.
align: Alignment within a text field. Allow values: 0 (left-aligned), 1 (centred), 2 (right-aligned). The default value is 0.
combo: A boolean key to indicate if the choice list is a combo menu. The default value is false.
default: The default value for a field.
hidden: A boolean key to indicate if the field is hidden. The default value is false.
menulength: The number of elements shown in a choice list. The default value is 4.
multiline: A boolean key to indicate if the text field is a multiline field.
name: The name of the field (defaults to the label if omitted). Note that the label is the text that appears by the side of the field (or on the button, in the case of a push button) whereas the name identifies the field when referenced in the script that processes the form.
password: A boolean key to indicate if the text field is a password field. The default value is false.
popdown: A boolean key to indicate if the choice list is a popdown menu. The default value is false.
radio: A boolean key to indicate if the choice list is a group of radio buttons. The default value is false.
value: The initial value for the field.

Example 58. A Simple Electronic Form

This example form doesn't have a submit button. Here, the user just fills in the form using the interactive elements and either prints it out or saves it. (The ability to save the PDF file depends on the PDF viewer, but if you aren't able to save it you may be able to print it to another PDF file, using a “print to file” option in your printer dialog.)

\documentclass{article}

\usepackage{hyperref}

\begin{document}
\begin{Form}
\TextField{Name}\qquad \TextField{Date}

\ChoiceMenu[combo]{Gender}{Male,Female}

\ChoiceMenu[radio]{Project}{cookies,cakes,chocolates,raygun}

Which ice cream flavours do you like?

\CheckBox{vanilla}
\CheckBox{mint}
\CheckBox{toffee}
\CheckBox{fudge}
\CheckBox[name=guarana]{guaran\'a}
\CheckBox{strawberry}
\CheckBox{raspberry}
\CheckBox{chilli}
\CheckBox{other}

\end{Form}
\end{document}

How the form elements are rendered depends on your PDF viewer. For example, Figure 11.5 shows this form displayed in Adobe Reader and Figure 11.6 shows the same file displayed in Google Chrome. For me, Google Chrome works best (except when it hangs) as there's no native 64 bit Linux version of Adobe Reader, which means I have to run Adobe Reader on Wine and some of the interactive elements cause it to crash. If you use another operating system, you may find that the Adobe PDF viewers, such as Adobe Reader, produce suitable results.

Unfortunately I can't find any other Linux-based PDF viewers that render this example correctly. Figure 11.7 shows the same PDF file viewed in Okular. This renders most of the interactive elements correctly, but fails on the group of radio buttons. Only the first radio button is correctly rendered as an interactive element. The other radio buttons appear as non-interactive open single quote marks. (These appear to be the decorative open quote mark ❛ from the ZapfDingbats font, \ding{123}.) A similar problem occurs with Evince and with the document viewer that comes with TeXworks. Other PDF viewers, such as Sumatra or the Linux version of Foxit (Figures 11.8 and 11.9), don't recognise any of the interactive elements (but Foxit on Windows does show the interactive elements, see Figure 11.10). Therefore, you will need to take care about your choice of PDF viewer if you want to create an electronic PDF form (and the PDF viewer for any users of your form).

**Figure 11.5:** Example Interactive PDF Form Viewed in Adobe Reader
⇩

**Figure 11.6:** Example Interactive PDF Form Viewed in Google Chrome
⇩

**Figure 11.7:** Example Interactive PDF Form Viewed in Okular
⇩

**Figure 11.8:** Example Interactive PDF Form Viewed in Sumatra
⇩

**Figure 11.9:** Example Interactive PDF Form Viewed in Foxit on Linux
⇩

**Figure 11.10:** Example Interactive PDF Form Viewed in Foxit on Windows
⇩

You may have noticed from the above example that each field's label (such as “Name” or “Project”) is placed to the left of the interactive element (or elements, in the case of the radio group). This layout is governed by:

\LayoutTextField {⟨label⟩}{⟨field⟩}

for text fields,

\LayoutChoiceField {⟨label⟩}{⟨field⟩}

for choice fields, and

\LayoutCheckField {⟨label⟩}{⟨field⟩}

for check boxes. These all default to ⟨label⟩ ⟨field⟩. Since the space is a regular breakable space, this allowed a line break to occur between the label “raspberry” and its associated check box (as can be seen, for example, in Figure 11.5). To prevent this, \LayoutCheckField can be redefined to use a non-breakable space:

\renewcommand*{\LayoutCheckField}[2]{#1~#2}

Alternatively, if you also want the check box and label swapped round, so that the label is on the right:

\renewcommand*{\LayoutCheckField}[2]{#2~#1}

Note that \LayoutChoiceField just controls the layout of the label for the list of choices and the choice list element or group of elements. In the case of a group of radio buttons, each radio button has a fixed layout with the radio button label first followed by a space and then the radio button. There's no user level macro for changing this layout.

The actual field display is given by:

\MakeRadioField {⟨width⟩}{⟨height⟩}

for radio fields;

\MakeCheckField {⟨width⟩}{⟨height⟩}

for check boxes;

\MakeTextField {⟨width⟩}{⟨height⟩}

for text areas;

\MakeChoiceField {⟨width⟩}{⟨height⟩}

for choice lists. These commands all default to creating a blank area of the given ⟨width⟩ and ⟨height⟩. (This is how, in Figure 11.9, the area taken up by the interactive elements appears as a blank space even though the fields aren't rendered. The actual rendering of the field is to some extent determined by the PDF viewer.)

The layout of the text on push buttons is determined by

\MakeButtonField {⟨text⟩}

This defaults to just ⟨text⟩.

The default dimensions are given by the commands:

\DefaultHeightofSubmit

for the default height of the submit button (14pt);

\DefaultWidthofSubmit

for the default width of the submit button (2cm);

\DefaultHeightofReset

for the default height of the reset button (14pt);

\DefaultWidthofReset

for the default width of the reset button (2cm);

\DefaultHeightofCheckBox

for the default height of check boxes (\baselineskip);

\DefaultWidthofCheckBox

for the default width of check boxes (\baselineskip);

\DefaultHeightofChoiceMenu

for the default height of choice boxes (\baselineskip);

\DefaultWidthofChoiceMenu

for the default width of choice boxes (\baselineskip);

\DefaultHeightofText

for the default height of single-lined text fields (\baselineskip);

\DefaultHeightofTextMultiline

for the default height of multi-lined text fields (4\baselineskip);

\DefaultWidthofText

for the default width of text fields (3cm). Note that these are all macros not lengths, so you need to use \renewcommand to change them. These defaults are used for fields that don't have the height or width options specified (in the optional argument of the field commands, such as \CheckBox).

Suppose now I want the check boxes from Example 58 to appear in a tabular layout, so that they appear more like those from Figure 11.2. A first attempt might look something like:

\renewcommand*{\LayoutCheckField}[2]{#2 #1}

Which ice cream flavours do you like? (Tick all that apply.)

\begin{center}
\begin{tabular}{lll}
\CheckBox{vanilla} &
\CheckBox{mint} &
\CheckBox{toffee}\\
\CheckBox{fudge} &
\CheckBox[name=guarana]{guaraná} &
\CheckBox{strawberry}\\
\CheckBox{raspberry}&
\CheckBox{chilli} &
\CheckBox{other}
\end{tabular}
\end{center}

However, this produces the form shown in Figure 11.11. The check boxes are far too narrow. Recall from above that the default width of the check boxes is given by \DefaultWidthofCheckBox, which is initialised to \baselineskip. One of the peculiarities of the tabular environment is that it temporarily sets the value of \baselineskip to 0 pt. This means that check boxes default to zero width when placed inside a tabular environment. Here's a second attempt that changes the defaults to depend on the font size instead:

\renewcommand*{\LayoutCheckField}[2]{#2 #1}
\renewcommand*{\DefaultWidthofCheckBox}{2ex}
\renewcommand*{\DefaultHeightofCheckBox}{2ex}

Which ice cream flavours do you like? (Tick all that apply.)

\begin{center}
\begin{tabular}{lll}
\CheckBox{vanilla} &
\CheckBox{mint} &
\CheckBox{toffee}\\
\CheckBox{fudge} &
\CheckBox[name=guarana]{guaraná} &
\CheckBox{strawberry}\\
\CheckBox{raspberry}&
\CheckBox{chilli} &
\CheckBox{other}
\end{tabular}
\end{center}

This produces Figure 11.12, which has check boxes with a better width, but the heights are too large causing them to overlap. In fact, they are higher than the specified 2 ex given in the redefinition of \DefaultHeightofCheckBox. This seems to be caused by the tabular environment stretching the boxes to fill the available height, but this occurs outside of the box created by \MakeCheckField.

Here's a third attempt that explicitly sets the width and height within the definition of \LayoutCheckField using a \parbox:

\renewcommand*{\LayoutCheckField}[2]{#2 #1}
\renewcommand*{\DefaultWidthofCheckBox}{2ex}
\renewcommand*{\DefaultHeightofCheckBox}{2ex}
\renewcommand*{\LayoutCheckField}[2]{%
 \parbox[\DefaultHeightofCheckBox]{\DefaultWidthofCheckBox}{#2} #1}

Which ice cream flavours do you like? (Tick all that apply.)

\begin{center}
\begin{tabular}{lll}
\CheckBox{vanilla} &
\CheckBox{mint} &
\CheckBox{toffee}\\
\CheckBox{fudge} &
\CheckBox[name=guarana]{guaraná} &
\CheckBox{strawberry}\\
\CheckBox{raspberry}&
\CheckBox{chilli} &
\CheckBox{other}
\end{tabular}
\end{center}

This produces the result shown in Figure 11.13, which now has square check boxes. Unfortunately this doesn't take into account the height or width options that may override the default sizes. In this case, that's not an issue as I want all the check boxes to be the same size. If you want larger check boxes in another area of the form, you can localise the effects of the above redefinition of \LayoutCheckField by scoping it. For example, by placing it inside the start of the center environment before the start of the tabular environment:

\begin{center}
\renewcommand*{\LayoutCheckField}[2]{%
 \parbox[\DefaultHeightofCheckBox]{\DefaultWidthofCheckBox}{#2} #1}%
\begin{tabular}{lll}

The other possibility is to use the internal commands \Fld@width and \Fld@height, which store the width and height for the check box:

 \parbox[\Fld@height]{\Fld@width{#2} #1}

However, be careful about using internal commands that aren't part of the LaTeX kernel as they may change with future versions. Also remember that internal commands must be placed inside a class or package or should be enclosed inside \makeatletter… \makeatother.

Figure 11.11: First Attempt at Laying Out Check Boxes in Rows and Columns

**Figure 11.12:** Second Attempt at Laying Out Check Boxes in Rows and Columns

**Figure 11.13:** Third Attempt at Laying Out Check Boxes in Rows and Columns

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).