Adobe acrobat forms javascript object specification User Manual

57

The user can add scripts to a form field definition using a dialog box in the form editing tool.
(see

section below). These scripts are executed as the events occur (e.g.

mouse up or calculate). Scripts that are field specific should be created at this level. Usually
these scripts validate, format, or calculate field values.

Unlike plug-in folder scripts, document level and field level scripts are stored within the PDF
document and therefore the forms programmer should make every effort to package his scripts
as effectively as possible (e.g. code reuse) at the various levels for performance and file size
reasons.

Form fields typically have names like FirstName, LastName, etc. This naming convention is
referred to as flat names. For many form applications, this flat hierarchy of names is sufficient
and works well. The problem with using flat names is that there is no association between the
fields.

Form field names can be more useful by creating a hierarchal structure. For example, if we
change FirstName to Name.First and LastName to Name.Last we form a tree of fields. The
period (‘.’) separator used in Acrobat Forms and denotes a hierarchy shift. The Name portion
of these fields is the parent, and First and Last become the children. While there is no limit to
the depth a hierarchical name can be constructed it is important that the hierarchy remain
manageable.

This hierarchy can be useful in a number of ways. It can speed up authoring and ease
manipulation of groups of fields in JavaScript. In addition, a form field hierarchy can improve
the performance of forms applications when there are many fields in the document.

Using our original flat names FirstName, MiddleName and LastName, imagine that we want to
change the background color of these fields to yellow (to indicate missing data, or emphasize
an important point). We would need two lines of JavaScript code for each field:

var name = this.getField("FirstName");

name.fillColor = color.yellow;

name = this.getField("MiddleName");

name.fillColor = color.yellow;

name = this.getField("LastName");

name.fillColor = color.yellow;

With our hierarchy of Name.First, Name.Middle and Name.Last above (and perhaps,
Name.Title if used), we can change the background color of these fields with just two lines of
code instead of six: