Entering scripts for form fields with Acrobat 6, 7 and 8

Learn about the two types of form-field scripts, widget scripts and scripts associated with the value of a field.

By Thom Parker – September 18, 2006

Scope: Acrobat Professional 6.0 and greater
Skill Level: Beginner
Prerequisites: Familiarity with Acrobat Professional

Form-field scripts can be divided into two areas: scripts associated with actions performed on the instance of a field on a page (also called Widget scripts — a specific instance of a field is called a Widget), and scripts associated with the value of a field.

The Widget scripts are for the mouse and field-focus actions performed by the user. The field-value scripts are related to internal actions Acrobat takes when a field value changes. The different types of scripts in each area are listed below.

Widget scripts:

“Mouse Enter”	Runs when cursor enters field
“Mouse Exit”	Runs when cursor exits field
“Mouse Up”	Runs when cursor is over field and mouse button is pushed
“Mouse Down”	Runs when cursor is over field and mouse button is released
“On Focus”	Runs when field gains keyboard focus
“On Blur”	Runs when field loses keyboard focus

Field-value scripts:

“Calculate”	Runs when any field value on the document changes
“Keystroke”	Runs for each keystroke entered into a text field
“Validate”	Runs when the associated field value changes
“Format”	Runs after the Validate script, but only if Validate returns true

All these scripts are accessed from the Field Properties dialog.

To display the dialog:

1. Activate the Select Object Tool on the Advanced Editing toolbar, Figure 1.

Figure 1: Activating the “Select Object Tool”
from the Acrobat “Advanced Editing” toolbar

2. Right click on the form field of interest. This action displays a context-popup menu.

3. Select Properties… from the menu. This action activates the Field Properties dialog, Figure 2.

Figure 2 – MouseUp Script set for a text field

Widget scripts

All field types have an Actions tab on their Properties dialog. This tab provides access to the Widget scripts. The “Select Trigger” pull-down list selects the action that triggers the script, MouseUp, MouseDown and so on. The “Select Action” pull-down list selects the type of action to be performed. For this tip we are only concerned with the “Run a JavaScript” action.

To add a new JavaScript action:

Select the desired trigger from the “Select Trigger” pull-down list.
Select “Run a JavaScript” from the “Select Action” pull-down list.
Press the Add button. This action will display the script editor.

If the field has existing actions, they will be displayed in the Actions window. Figure 2 (above) shows the Properties dialog for a text field with a previously defined “MouseUp” script.

To edit an existing script:

Select the script from the Actions window.
Press the Edit button.

Field-value scripts

Separate tabs are provided on the Field Properties dialog for each of the field-value scripts. Since different types of fields have different types of values, these tabs are different for each field type. For example, the button field does not have any field value scripts since it doesn’t have a value, while the text field uses all the different field scripts. The table below lists the field-value scripts used by each field type.

There are several cases where Acrobat does not provide a user interface for accessing a particular script, yet the field will still run the script if it exists (marked as “No UI”). Acrobat does not provide a user interface because these scripts are not used with the particular field type under normal circumstances. However, this doesn’t mean that these scripts could not be useful, so ambitious users can still set the scripts using a JavaScript function.

Field Type	Format	Keystroke	Validate	Calculate
Button	X	X	X	X
Text	Yes	Yes	Yes	Yes
Check Box	X	No UI⁽¹⁾	No UI⁽¹⁾	No UI⁽¹⁾
Radio Button	X	No UI⁽¹⁾	No UI⁽¹⁾	No UI⁽¹⁾
Combo Box	Yes	Yes	Yes	Yes
List	X	Yes⁽²⁾	No UI⁽¹⁾	No UI⁽¹⁾
Signature	Yes⁽³⁾	No UI⁽¹⁾	No UI⁽¹⁾	No UI⁽¹⁾

⁽¹⁾ Acrobat does not provide a user interface to these scripts, but they can be set from the Console Window with the setAction() JavaScript function.

⁽²⁾In the List Field the Keystroke script is called the Select Change script.

⁽³⁾In the Signature Field the Format script is called the Signed script.

The text field uses all four of the field-value scripts, so we’ll use it as the example in the following discussion.

Format and Keystroke scripts: (both are on the same tab)

In the text field, the Format and Keystroke scripts are used together to enforce formatting. The Keystroke script ensures that only certain keys are entered and the format script adds the final touches when field data is committed.

To access:

1. Open the Field Properties dialog.

2. Select the Format tab.

3. On Select format category, choose “Custom.” This action displays the Format and Keystroke scripts (Figure 3).

4. Push the edit button for either Format or Keystroke to create a new script or edit an existing one.

Figure 3 – Entering the Format and Keystroke scripts

Validate script:

The Validate script is run when a field value is committed. When users press the Enter key or tab out of the field, they are indicating the entered data should be put into the field value, called “committing” the value. The Validate script sits between the user action that signals the value should be committed (tabbing, pressing Enter or selecting another field) and the actual value being committed.

To access:

Open the Field Properties dialog.
Select the Validate tab.
Select the Run custom validation script radio button (Figure 4). Be careful with these radio buttons. When another option is selected, the existing validation script is lost.
Push the edit button to create a new script or edit an existing one.

Figure 4 – Entering a Validation script

Calculate script:

Calculate scripts are run when any field value on the document is changed.

To access:

Open the Field Properties dialog.
Select the Calculate tab.
Select the Custom calculation script radio button (Figure 5). Be careful with these radio buttons. When another option is selected the existing validation script is lost.
Push the edit button to create a new script or edit an existing one.