Custom Format for PDF Fields
A custom format script can be used to display something in the field prior to data entry.
PDF text fields can be programmed to only accept input in a specific format. The format tab of the field properties has a dropdown with a list of five built-in formats and one place to enter a custom format script:
Number
Percentage
Date
Time
Special
Custom
The number format has several options including currency symbols, separator style, and number of decimal places. The date, time, and special formats also have several options. These options actually contain custom format scripts combined with custom keystroke scripts that aren’t seen in the properties and operate behind the scenes.
In Using JavaScript To Add JavaScript to a PDF Part 2 I described how to find these custom scripts and set them programatically using the setAction method.
Custom Format Scripts
A custom format script can be used to display something in the field prior to data entry. The format is not the value of the field. So the field can appear to display a value without actually having a value. For example, I have seen text fields on forms with text that says something like "Please enter your name". The form designer simply entered this text as the default value of the field, so Please enter your name is actually the value of the field. When users click into that field they would have to highlight all the text and start typing in order to replace it. Tabbing into the field instead would automatically highlight all the text.
What if you wanted the field to display text before the field has a value, and replace the text with the value entered by the user? You would simply write a custom format script that says if this field does not have a value, display this value. Before you click or tab into a field formatted this way, the default text is present. It disappears when the focus is on the field. Whatever you type replaces the default text. If you tab out or click elsewhere without typing a value, the original text reappears.
Practical Example
Suppose you wanted to guide the user to enter the specific date format of mm/dd/yyyy into a field. You would simply enter the following custom format script:
if(!event.value)
{event.value="mm/dd/yyyy"}The field will display "mm/dd/yyyy" until the text is replaced. If the field is cleared it will display "mm/dd/yyyy" again. This does not solve the issue of the user entering an incorrect format. Any text will be accepted and replace "mm/dd/yyyy".
Combine Custom Format Script With Date Format
Remember, a field formatted for a date contains a format script as well as a keystroke script. The scripts for the previously mentioned date format are as follows:
//Custom format
AFDate_FormatEx("mm/dd/yyyy");
//Custom keystroke
AFDate_KeystrokeEx("mm/dd/yyyy");When both of these scripts are entered, either manually or by the setAction method, they will not be seen in the format tab of the field properties. Instead, the date format will be displayed.
If you combine these scripts you will have the best of both worlds: The date format appearing in the text field when no value is present, and the field formatted to accept a specific date format only. Any other entry will result in a popup error message about the format:
To combine the scripts enter the following custom format script and custom keystroke script:
//Custom Format Script:
if(!event.value)
{event.value="mm/dd/yyyy"}
else
{AFDate_FormatEx("mm/dd/yyyy")};
//Custom Keystroke Script
AFDate_KeystrokeEx("mm/dd/yyyy");Expand With More Features
Suppose you want to change the text color and font when the default format is displayed and have it display differently once a correct date is entered - maybe a light blue color and Times Bold font for the format display and black text with Helvetica for an actual value.
Suppose you also don’t want the default format to print when the form is printed but you want the entered date to print. You can simply enter these changes in the custom format script under the conditions (whether the field contains a value or not).
if(!event.value)
{
event.value="mm/dd/yyyy";
event.target.textFont="Times-Bold";
event.target.textColor=["RGB",0,0.502,0.752];
event.target.display=display.noPrint;
}
else
{
event.target.textFont="Helvetica";
event.target.textColor=color.black;
event.target.display=display.visible;
AFDate_FormatEx("mm/dd/yyyy");
};
The custom keystroke script would not change.