Conditional execution and Acrobat JavaScript

This pseudo code shows the simplest way to write a decision block. This particular "if" block can be divided into two parts-- the condition, and the code that is run when the condition is met. The condition is a short piece of code that results in a true or false value, and it is called a Boolean Expression.

Value comparisons and the Boolean expression

Boolean Logic is a system of mathematics that deals with true and false values, called Boolean values. As we will see, Boolean Logic is actually very simple and it is a key element of computer programming. A Boolean expression is a piece of code that operates on, and/or results in, a Boolean value. Boolean expressions are created using the comparison and Boolean operators. In our previous example, the condition is the expression:

nSubTotal > 100

where the operator is the Greater Than, ">", comparison operator. If nSubTotal is greater than 100, the expression returns a value of True; otherwise it returns a value of False. The other comparison operators are: Less Than; "<", Equals to; "==" and Not Equals; "!=". There are also compound-comparison operators that combine Greater Than and Less Than with Equals to; "<=" and ">=". All these comparison operators return Boolean values. Most of the time, they will be the starting point for a Boolean expression, converting values from the form into true or false values that will be used to make decisions with an "if" statement.

It’s important to note that these comparison operators work for both number and text values. This is important because many of PDF form fields return text values. For example, both radio buttons and checkboxes export a text value. The checked or selected value is set by the form designer, but the unchecked/unselected value is always "Off." We can use this value in a Boolean expression to detect and make decisions based on the unchecked checkbox, or the unselected Radio button group.

The code below is used in a form-level validation script to let users know they have to check "I Agree" before submitting a form:

var cAgree = this.getField("AgreeCheck").value;
if( cAgree == "Off" ) app.alert("You must select ‘I Agree’ before continuing");

So now we’ve seen how to create a simple Boolean expression by using a comparison operator to compare two values to one another. But what do we do if our condition is more complex? For example, what if we need to test that a field value is within a range between two values, or something even more complex? To handle these situations, we need to write a Compound Boolean expression.

Compound Boolean expressions

Complex Boolean expressions are created by combining simple expressions with the Boolean operators. The basic Boolean operators are: And; "&&", Or; "||", and Not; "!". Along with grouping sub-expressions in parentheses, these operators can be used to create conditional expressions for almost any situation you will ever need. In fact, as previously stated, there is a whole branch of mathematics devoted to studying Boolean expressions. But for our purposes here, and for the majority of situations you’ll be dealing with, we can stick to the basics.

To write a complex expression, it first has to be expressed in English. In our first example, a discount was created based on the subtotal being greater than 100. Let’s modify that condition to this: "If the subtotal is greater than 100 and the subtotal is less than or equal to 200, then apply a 10% discount." This conditional contains a second condition tied to the first part with "AND." The "AND" means both parts have to be true in order for the total expression to be true. The implementation is exactly as stated.

event.value = 0;
// Initial discount value var nSubTotal = this.getField("subtotal").value;
if ( (nSubTotal > 100) && (nSubTotal <= 200) ) event.value = nSubTotal * 0.10;

This code is nearly the same as the first example. The only difference is the addition of the second condition. But there are a few very important details here worth noting. The first is the use of the compound comparison operator "<=". Using this operator has made our job much easier because it’s packing two comparisons into one. The sub-expression returns true for two conditions, subtotal is less than 200 and subtotal is equal to 200. Without the compound comparison operator, we’d have to write the expression with three conditions.

The second detail of note is that the two comparisons are grouped using parentheses. This is important for two reasons. First, it makes reading the code easier, and second, it ensures proper execution of the expression. Strictly speaking, the parentheses are not always necessary, but unless you are an expert at precedence of operator execution, you should always group the sub-expressions you want to execute as a single entity. Otherwise, the JavaScript engine may just decide to do the execution differently.

And finally, we get down to the "&&". This operator only returns true if both conditions are true, so this is where we need to make sure our conditions make sense. You can very easily write nonsensical expressions. For example, here’s a small change to our Boolean expression.

(nSubTotal < 100) && (nSubTotal > 200)

There is nothing wrong with this code as far as the Acrobat JavaScript engine is concerned. It will not complain, but obviously this expression will never be true. A number cannot be both less than 100 and greater than 200. This may seem silly, but it is surprisingly easy to set up unrealistic and conflicting conditions.

To stretch this concept a bit further, let’s add an additional layer of complexity by also applying the discount when the customer is a member of our company website, as indicated by a checkbox on the form. So, our statement of conditions is now: "If the subtotal is greater than 100 and the subtotal is less than or equal to 200, or if the members checkbox is checked, then apply a 10% discount." The "if" statement is shown below, but for brevity, the supporting code is not included; and to make the groupings more obvious, the parentheses are color-coded:

var bMember == this.getField("MemberCheck").isBoxChecked(0);
if ( ( (nSubTotal > 100) && (nSubTotal <= 200) ) || bMember) <. . .>

Notice that our original two conditions are grouped, making them a single entity in the expression and allowing us to use the original expression unchanged. Expressions and sub-expressions can be nested within parentheses as deep as necessary to create the condition. The total condition here is true if either the checkbox is checked or our original set of conditions is true.

The final logical operator "!" is used to invert the return value of a sub-expression. Let’s change the expression to only apply the discount when the customer is not a member. So here’s our new statement of conditions: "If members checkbox is not checked and the subtotal is greater than 100 and the subtotal is less than or equal to 200, then apply a 10% discount." In this case, we are not using an OR operation. Instead, we are adding to the AND of the original conditions. Here’s the if code:

if ( !bMember && (nSubTotal > 100) && (nSubTotal <= 200) )
<. . .>

Now we’re ready to move on to the next level of complexity, setting up multiple conditions.

Multiple conditions

All conditional expressions have two results. The condition is met, or it’s not met. So far, we’ve only looked at running code for the situation where the condition is met. But we can also run code for the negative result by constructing the "if" statement with an "else" section, like this:

if(  )  else 

var nSubTotal = this.getField("subtotal").value;
if( nSubTotal > 100) event.value = nSubTotal * 0.10;
else event.value = 0;

var nSubTotal = this.getField("subtotal").value;
if( nSubTotal > 200 ) event.value = nSubTotal * 0.20;
else if( nSubTotal > 100 ) event.value = nSubTotal * 0.10;
else if( nSubTotal > 50 ) event.value = nSubTotal * 0.05;
else event.value = 0;

var nSubTotal = this.getField("subtotal").value;
if( nSubTotal > 100) {
	event.value = nSubTotal * 0.10;
	app.alert("Congratulations, you get a discount",2);
} else {
	event.value = 0; app.alert("Sorry, no discount for you",2);
}