Calculation vs. Validation Scripts II

Different methods for non-text fields

In my last article I outlined the difference between custom calculation and validation scripts for text fields, and how to use them. Check box and radio button fields do not have calculation or validation tabs in the field properties. List box fields do not have a validation tab, but they have a Selection Change tab that is very similar to a validation tab because it executes a script when the value of the list box changes, which is what a validation script in a text field does. Dropdown fields have the same calculation and validation tabs as text fields. However, because dropdowns can have two values (display and export) as outlined here, there is often confusion about how to properly execute a validation script.

Check Box Calculation Script

Since check box and radio button fields are almost identical in what they do and how they react, I will reference only check box fields for both. As previously stated, check box fields do not have a calculation tab. Since calculations run every time any field value changes, a calculation script pertaining to a check box field can be inserted in any text field. If you need a calculation script for a check box, simply create a hidden text field to run the calculation.

Check Box Validation Script

A validation script runs whenever the value of the field containing that script changes. Check box fields do not have validation tabs. Instead of a validation script you can use a mouse up action. The script runs after the mouse button is pressed down on the check box and released back up. The value of the check box is the value that it changed to after the selection. The value of a check box (or radio button) in a mouse up action script is called using event.target.value, rather than event.value as with other field types. If you have a group of radio buttons or check boxes that act like radio buttons by having the same field name, but different export values, the script needs to be inserted into each field.

Check Box Values

When you create a check box field the default export value is Yes. This is also the value of the field when it is checked. You can change the export value to any value you want. The value of an unchecked check box is Off. A series (same field names) of check boxes with different export values are mutually exclusive (only one in the series can be checked). The export value of the one that is checked is the value of the field when called from a script. If all are unchecked the value is Off.

Example 1

In this example, the check box will set the visibility of a text field named Text1. The script is in a mouse up action so it acts like a validation script.

if(event.target.value == "Off")
{this.getField("Text1").display = display.hidden}
else
{this.getField("Text1").display = display.visible}

If the value is Off (unchecked) the field is hidden. If the value is not Off, the field is visible.

Example 2

In this example, the check box sets the value of Text1, base on the check box’s export value, unless its value is Off, in which case the value is set to an empty string.

if(event.target.value != "Off")
{this.getField("Text1").value = event.target.value}
else
{this.getField("Text1").value = ""}

If there are multiple check boxes with the same name, the script should be entered as a mouse up action in all of them. The value of Text1 can still be changed by the user because the mouse up action acts like a validation script (see Calculation vs. Validation Scripts). A calculation script can be used in Text1 instead so that the value can only be changed by changing the check box values like this:

//Field name is Check Box1
if(this.getField("Check Box1").value != "Off")
{event.value = this.getField("Check Box1").value}
else
{event.value = ""}

How To Create a PDF Check Box Scoring Questionnaire in Five Minutes

List Box

A list box can have display values as well as export values that correspond with each display value. If the display value does not have an export value, the display value is the export value. For example, the list box pictured below has display values of nothing, A, B, and C.

List Box Field

It can have no corresponding export values, in which case the export values would be nothing, A, B, and C. It could also have corresponding export values. In this example I will use nothing, 1, 2, and 3. Nothing is an empty string and can only be set using a script.

PDF List Box with corresponding export values

I developed a tool for filling list box and dropdown fields with entries by copying and pasting columns of entries into a window:

Calling List Box Display Values From A Script In The Field

When calling the display (or item) value of a list box field, whether the field contains export values or not, use event.value. Example:

this.getField("Text1").value = event.value;

Make sure Commit selected value immediately is selected in the Options tab of the list box.

All list box scripts are entered in the Selection Change tab.

Calling List Box Export Values From A Script In The Field

It’s a little trickier to call the export values from a script in a list box field. The export value can be called with event.changeEx. When this value is called from a script in the selection change tab it calls the export value after the change. However, it won’t work unless another piece of code is added. event.willCommit verifies the keystroke event before the data is committed (you make a selection but the change is not yet committed - event.willCommit is true). That means event.changeEx returns nothing because it's calling the changed value before the change was committed. By testing whether event.willCommit is false before committing the data you will get the correct export value result like this:

if(!event.willCommit)
{this.getField("Text1").value=event.changeEx}

Calling List Box Export Values From A Script In Another Field

Simply use the field's value like this:

//List Box field name is List Box1
event.value=this.getField("List Box1").value

If the list box does not have export values and the script above is entered as a custom calculation script in a text field, the value will calculate to the display value of the list box. If the list box has export values, the value will calculate to the export value of the list box. What if the list box has export values but you want to call the display value of the list box from another field?

Calling List Box Display Values From A Script In Another Field

In this case you will need two different scripts:

1) this.getField("List Box1").getItemAt( )

2) this.getField("List Box1").currentValueIndices;

The first script obtains either the export value or the display value and takes two input parameters:

1) The zero-based index number of the item in the list box (1st item is 0, 2nd is 1, etc.)

2) true or false, representing whether the export value is used (true) or not (false). If you want to get the export value you would set this parameter to true. If you want to use the display value you would set the parameter to false.

The following script sets the value of Text1 to A:

event.value=this.getField("List Box1").getItemAt(1,false);

with 1 being the 2nd item in the list box. The following script sets the value of Text1 to 1:

event.value=this.getField("List Box1").getItemAt(1,true);

This is not helpful for changing list box when you want the text field's value set to the current value of the list box. Fortunately, there's a script to get the index number of the current item in the list box: this.getField("List Box1").currentValueIndices. Here’s how to implement this script:

//set field's value to the current display value of the list box
var oFld=this.getField("List Box1");
event.value=oFld.getItemAt(oFld.currentValueIndices, false);

//set field's value to the current export value of the list box
var oFld=this.getField("List Box1");
event.value=oFld.getItemAt(oFld.currentValueIndices, true);

/*As stated previous, setting the field's value to the current export value of the list box can also be written as follows:*/

event.value=this.getField("List Box1").value;

Dropdown Fields

Everything above regarding list box fields is identical for dropdown fields, except:

• The changeEx scripts are entered as custom keystroke scripts in the Format tab of the dropdown field.

• All the other scripts for the dropdowns are entered as custom validation scripts in the validation tab. Dropdowns don’t have a Selection Change tab.

The Selection Change tab in list box fields is for both validation and keystroke scripts. In dropdown fields, the validation tab is for validation scripts and the Keystroke field in the Format tab is for custom keystroke scripts. The changeEx scripts are keystroke scripts.