Formatting text fields

Learn about two ways of handling text field formatting: the Keystroke (change) event and the Format event.

By Thom Parker – July 7, 2006

 

Scope: All Acrobat versions
Skill Level: Intermediate
Prerequisites: Familiarity with Form Fields and the JavaScript environment

Acrobat provides two events (script locations) for handling text field formatting. The Keystroke (change) event and the Format event. Together, these events can be used to control both the format of data entered into the field and the appearance of the data displayed in the text field. All scripts covered in this tip, plus additional examples, are provided in the FormattingExamples.pdf file.

Formatting Examples
Download FormattingExamples.pdf

The Keystroke Event

The Keystroke is called in two different situations. First, it is called for each change made to the field during data entry. Typically this means for each of the user’s keystrokes, but it is also called when data is pasted into the field from the clipboard. The data being entered is stored in a temporary location and does not change the real value of the field until the user either presses the enter key or tabs out of the field. The process of applying the entered data to the actual field value is called “committing.” The second situation in which the keystroke event is called is immediately before the data is committed to the field value. For convenience we’ll call this the WillCommit event. The Event Object provides the event.willCommit property to distinguish between these two situations.

These two situations provide us with a way to manipulate the entered data in two ways. The first allows us to filter and replace the data as it is entered. For example, to guarantee the user will enter a numeric value, the following Keystroke script rejects any keystrokes that are not a number or a decimal point by setting the event return value, event.rc, to false;

if(!event.willCommit)     
    event.rc = !isNaN(event.change) || event.change == ".";

By testing the willCommit property, the script only processes events caused by user keystrokes. The event.change property holds the value of the keystroke or clipboard paste. It is this property that needs to be tested for acceptable input data. Since the value of event.change can be more than one character in length it is important to write the code to handle any number of characters.

The Keystroke event that occurs immediately before the entered value is committed, the WillCommit event, gives the script a final chance to reject or changed the entered data. For example, with the previous script it is possible to enter illegal number formats like “11.22.33”. This number is illegal because you can’t have two decimal points in a number. The following script corrects this problem by using the WillCommit event.

if(!event.willCommit) {
    // Test individual keystrokes and clipboard pastes     
    event.rc = !isNaN(event.change) || event.change == "."; 
} else {
    // Test the entire pre-commit value     
    event.rc = !isNaN(event.value); 
}

Returning false from the WillCommit event rejects the entered value and aborts event processing for that field. This means that the field returns to its previous value and that neither the Validate nor Format field events are called.

Another way to use the Keystroke event is to replace the input. For example, the following Keystroke script forces all characters entered to be upper case.

if(!event.willCommit)     
    event.change = event.change.toUpperCase();

The Format Event

Keystroke filtering and substitutions made with the Keystroke event occur before data is committed and change the real value of the form field. On the other hand, changes made with the Format event happen after the data is committed. It changes the appearance of the form field, not the field’s value. This is useful for any number that requires special symbols when displayed to the user, such as currency. For these values the currency symbol is very important, but it is also important for the field value to be a number so it can be used in calculations. The symbol can’t be part of the actual field value. The following Format script prefixes the field value with a British Pound symbol.

event.value = String.fromCharCode(0x0A3) + event.value;

The appearance of the field is changed so the user always sees the currency symbol prefixed onto the number, but the real value of the field is unchanged. As an extreme example of this idea, the following script displays the words “Blocked” no matter what the user types into the field.

event.value = "Blocked";

Another way to use this event is to convey special value information to the user. In the following Format script a red “NA” is displayed if the field value is less than or equal to zero. Note that a non-numeric field value will cause the script to fail. The validity of the data is not tested here. It is assumed the field already has a Keystroke script (like the one shown above) guaranteeing only numbers are entered.

if(event.value <= 0) {     
    event.value = "NA";     
    event.target.textColor = color.red; 
} else     
    event.target.textColor = color.black;   

Much more complicated formats are possible by using these events with regular expressions. But that’s another Tip.