PDF Form Reset Tricks
Tricks for Programming a PDF Form Reset Button and How To Clear Button Icons
There are several items in the Select Action dropdown in the Actions tab of the properties of a PDF form field. There is one called Reset a form, to create a form reset button. I never use it. In my very first Substack post How I Became a PDF JavaScript Expert I explain why I only use one item from this dropdown: Run a JavaScript.
Take the Acrobat Pro/JavaScript eLearning Course Acrobat Like a Pro
My Issue with The Reset A Form Option
When you first select this option for a field, a popup selection window appears with all fields that can be reset (basically, all field types except button fields – I'll examine this later). The default is that all fields in this window are already selected. That's great if that's what you want. If you only want to reset a section of the form when the user clicks your reset button, you either have to click Deselect All and then manually select the fields you want to reset, or manually unselect the fields you don't.
Suppose you do what I described in the previous sentence for a small section of the form, then continue to build your form. Here's the problem:
Every time you add a field (except a button field) it will appear in the window, and it will be automatically selected. To save yourself a lot of extra work and aggravation you'd have to remember to program this button last so no fields are automatically added and selected.
Alternatively, you could use Run a JavaScript.
The Form Reset Script
The document method resetForm( ) takes one optional input parameter, aFields, which is an array of field names to reset. If the parameter is omitted, all fields in the document will be reset. For a reset button in which all fields will be reset you would enter the following script under Run a JavaScript in the Actions tab of the button, with a Mouse Up trigger:
this.resetForm();Suppose you want to reset only three fields named First Name, Last Name, and Address. You might see the script written like this:
var fields = new Array();
fields.push("First Name");
fields.push("Last Name");
fields.push("Address");
this.resetForm(fields);Or like this:
var fields = ["First Name", "Last Name", "Address"];
this.resetForm(fields);You won't catch me writing the script either of these ways. If you read my column, you know one of my scripting rules:
“Only define a variable if you need to use it more than once. ”
I don't define variables unless I need the object of that variable more than once in my script, otherwise I waste time with extra, unnecessary typing. I would write the script with one line of code like this:
this.resetForm(["First Name", "Last Name", "Address"]);All three are correct and will achieve the desired result, but I prefer the most streamlined option.
The beauty of using a script instead of the Reset a Form User Interface (UI) option is that you can specifically name the fields without having to worry about other fields being added to the list. In this example there are only three fields that need to be reset, a common occurrence for a specific section of a form. Probably more common is when most of the fields, except a select few, need to be reset. Imagine having to type the name of 150 fields into an array to reset all but three fields. Using a script to reset an array of fields would not be much of a solution. Luckily, I have one for you if you keep reading, but first…
Field Default Values
A common misconception of resetting a form (whether using the UI or a script) is that it clears the fields. Technically, it sets the values of the fields to their default values. When a default value has not been set to anything, the default value is nothing, so in this case the field is cleared.
Text Fields
For a text field you can set the default value in the Options tab of the field properties or run the following script in the console:
this.getField("myField").defaultValue="ABC";
//sets the default value of a field named 'myField' to "ABC"When the form is reset the value of myField will revert to ABC. The value can be a string or number.
Dropdown and List Box Fields
For dropdown (combo box) fields and list box fields, the default value can also be set in the options tab by selecting the value from the list of items.
In the image above, the default value is A. It can also be set using the same script for a text field, as long as the value is in the list, or the Allow user to enter custom text box is checked. If the box is checked, you could use a script to set the default value to "D" for example. You wouldn't see the default value anywhere. When the form is reset, the value would change to D, but D would not be an option in the dropdown list. If another selection was made, D couldn't be selected again by the user without resetting the form. After the box is checked, and a script is used to set the default value to something that is not in the list, and the box is then unchecked, the field will still revert to the default value that was set with the script, even though this value is technically not possible.
Check Box and Radio Button Fields
For check boxes and radio buttons the default value is "Off". In other words, resetting the form will clear these field types. However, the default can be changed so the field is checked (selected). This is also done in the options tab of the UI by checking the box:
Check box is checked by default (Check box field) Button is checked by default (Radio button field)
The default value can also be set with the same script as the other two examples, except the default value is the export value of the field. Running the script will simply check the Check box is checked by default box or Button is checked by default box.
Signature Fields
Signature fields are cleared when they are reset. If the signature field is signed the signature is removed.
Barcode Fields
Barcode fields don't change if they are reset, but since they represent values from other fields, if any of those other field values change when the form is reset, the barcode will change to reflect the different values of the fields it represents.
Script to Prevent Fields from Resetting
If you have a reset button and you want it to reset most of the fields, but there are some fields you don't want it to reset, you can use this.resetForm() to reset all the fields, and then enter a simple line of code in the fields you don't want to reset. This avoids having to type multiple field names into an array in your reset script. An example might be a form that you need to complete multiple times and save, but there are certain fields with values that will never change once entered. You can complete the form, save it, click the reset button and start again. When you click the reset button it will clear all the fields except the ones to which you added the script. What is the script?
event.target.defaultValue = event.value;This script changes the default value of the field to the value of the field. In other words, when ever the value of the field changes by the user entering a value, the default value also changes, so when the form is reset the field appears to NOT reset because it is being reset to the existing value (which is the new default value). Where does the script go?
Custom Calculation vs Custom Validation Script
A custom calculation script runs every time the value of any field in the form changes. A custom validation script runs only when the value of the field containing the script changes. Since the script only needs to run when the field value containing the script changes, it should be entered as a custom validation script. Only text fields and dropdowns have a validation tab for entering a validation script. List boxes have a Selection Change tab, similar to a validation tab, where the script can be entered.
To summarize, when most fields except selected fields need to be reset with a reset button, enter the script as a custom validation or selection change script in those fields that won't be reset, and use this.resetForm() in the reset button.
Button Field Images (Icons)
A button field can have several appearance layouts:
If the behavior is set to Push, there are three optional mouse action states (Up, Down, and Rollover) for which a different layout can be used. I won't be discussing the different behaviors. If any of the layouts containing the icon option are used, a button field can be programmed so the user can import an image (icon) to the button face.
Adobe recently added an image field type to the Acrobat UI so this type of field could be placed without any programming. It is actually a button field with four features:
1) The layout is automatically set to icon only.
2) The script for the user to import an icon is already in the field. The script is a Mouse Up trigger in the Actions tab. The script is as follows:
event.target.buttonImportIcon();3) The field has a non-printable icon image to let the user know that an image can be added by clicking the field. Once an image is selected the icon pictured below is no longer visible.
4) The name of the button field is appended with _af_image to generate the image in the previous point. If _af_image is removed from the field name or altered, the icon pictured above will no longer be displayed.
You can use the import icon script in a regular button field and force the non-printable icon image by appending your field name with _af_image. As long as the layout is Icon only, no image has been selected yet, and the behavior is None, the non-printable icon is displayed. Once an image is selected by the user the icon above is no longer visible.
Clearing The Icon from a Button Field with a Reset Button
Acrobat has a JavaScript for almost every setting of every field type. Some things, however, can only be done with the UI. The Clear button in the Options tab of a button field, that clears an icon that has already been selected, is one of those. There is no "clear button icon" JavaScript method. Such a method would be useful for a form with the need for a reset button that would clear button icons selected by the user. Since no such method exists, a creative workaround needs to be deployed.
There's a field method to set the icon of a button field, buttonSetIcon(), that takes an icon as the first input parameter. The second parameter specifies which state the icon is for if the button behavior is push. This parameter is optional and won't be used here because the behavior will be None.
There's also a field method to get the icon from an existing field, buttonGetIcon() that can be used as the input parameter for the buttonSetIcon method. The optional input parameter specifies which state the icon is for if the button behavior is push. This parameter won't be used because the behavior will be None. Assume the name of the button field to set the icon is called Set, and the name of the button field to get the icon from is called Get. Here's the script to set the icon of Set with the icon of Get:
this.getField("Set").buttonSetIcon(this.getField("Get").buttonGetIcon());To use this script to clear the icon of Set, simply set the layout of Get to Icon Only, but don't set an icon for it. Then hide the Get field, since its only use is to clear other button icons.
Script To Clear All Button Fields That Contain Icons
In this example, the hidden field will be named Decoy instead of Get. The script will loop through all fields in the form and test:
1) Whether the field type is "button". 2) Whether the button field's layout is "Icon only". (Only button fields have the layout property so if you don't first test whether the field type is a button, an error will break the script).
If both tests are true, the icon will be set with the icon from the Decoy field, which is hidden and has no icon. The end result will be that the icon is cleared. A script can be added to the resetForm( ) script in the reset button:
for(var i = this.numFields - 1; i > -1; i--)
{
var fieldName = this.getNthFieldName(i);
if(this.getField(fieldName).type=="button" && this.getField(fieldName).buttonPosition==position.iconOnly)
{this.getField(fieldName).buttonSetIcon(this.getField("Decoy").buttonGetIcon())}
}The script above can be written as function, added as document level script, and then called in the reset button. If you have any questions about this post please feel free to ask me in the comments below. See you next time…