Figure 18.5 shows the purchaseOrder.pdf form from the book's CD-ROM. Acrobat's auto field detection didn't recognize any fields on the form, so we had to add all the fields manually. As you can see in Figure 18.5, the Item Total column contains ten fields using hierarchical names. The first field below the tenth row is used to calculate a subtotal.

Figure 18.5. An Item Total column contains fields using hierarchical names. Below the last row, a total of the amount fields needs to be calculated.

We use this form as an example to keep the scripting simple. For purchase order forms, any taxable items generally contain sales tax in each row total, so you may not need a separate field for tax on purchase order forms you design for your company. We broke this form up to illustrate different formulas you may need to use on forms, so focus on the process we describe in this chapter and not so much on the design of the sample form.

On some forms, you might not have a separate tax field like the one shown in Figure 18.5. For any form where sales tax is added to an amount total using a single calculation, you need to use JavaScript.

For the example form, we can use the preset sum + formula in the subtotal field to calculate the total for the Item Total column; but because we're talking about JavaScript, we'll use a script to total the column. Later, we talk about why we use JavaScript when we come to "Hiding zeros" later in this chapter.

Although the calculation to sum a column or row using JavaScript involves several lines of code, copying and pasting the code into additional forms is very easy. To create a JavaScript to sum a column, follow these steps.

STEPS: Summing a Column of Fields Using JavaScript

We introduce a few new routines in the script shown in Figure 18.6. We start the routine by assigning the parent name amount to variable f. If you followed other steps in Chapter 17 and this chapter, this assignment should be familiar to you.

In line 2, you find a new object. We set up an array and assign the array to variable a. Another item that's new is the loop we introduce in line 4. We first set the counter i to zero. The i < a.length item tells Acrobat to run the loop until the value i is less than the total number of rows. But we need to increment the i value through each pass in the loop, which is what the i++ item does.

In line 3, we set a variable sum to zero. In line 5, you see the sum value incremented with each pass in the loop. As the first row value is acquired, the a item is the field value and the i item is the counter. The last line of code (line 6) is the total sum we place as the event.value.

What's especially nice about this script is that you can add the script to a document where you collect an assortment of scripts as explained in Chapter 16 and paste the script into a document you use to collect various scripts. When it comes time to use the script, copy it from your template file and paste it in any form needing a similar calculation.

The only concern you have is just making sure you use the correct parent name for a row or column of fields. It you use the Place Multiple Fields command, Acrobat names the fields in hierarchical order. If you use a name like total, just replace amount in the first line of code with total. Every other line of code remains the same.

At the end of the script, you have a value sum. If you want to add a sales tax with a fixed tax rate, you would add a line 7 to the code, such as:

sum = sum + (sum * .075)

The above line of code adds a sales tax of 7.5 percent to the total. If you want a discount applied to the total, you might add a line 7 as follows:

sum = sum - (sum * .15)

This line of code creates a total less 15 percent.

The important thing to remember is that you have lots of flexibility for using the script shown in Figure 18.6 and can add just one more line of code for calculating various totals.

Using a tax rate in a field calculation for a fixed rate is nothing more than adding the formulas as:

1. var f = this.getField("amountFld");
2. event.value = f.value * .085;

The simple two-line script assigns variable f to a subtotal field or an amount field ("amountFld") you want to use for taxable items. Line 2 contains the fixed rate. In this example, the tax rate is 8.5 percent.

If you use a script like this on your forms, any change in tax rate requires you to edit the calculation script and change the rate to a new rate value.

Tax rates can vary among U.S. states and among different counties within a state. If you use forms that require calculating tax for each individual location where products are purchased, adding a user-supplied tax rate field might be the best way to calculate the tax. The formula uses the tax rate input to calculate the result.

In Figure 18.7, a tax rate field is used for a user-supplied tax rate. The Tax field is calculated based on the rate entered for this field.

Figure 18.7. A user-supplied tax rate field is used in the tax amount calculation formula.

To calculate a tax rate based on user input for the rate amount, follow these steps.

STEPS: Calculating Sales Tax Based on User Input Rate Values

We start the script off in line 1 in Figure 18.8 by looking at the subTotal field. If the field is not yet populated with data, the calculation script is not run. This line prevents a calculation on zero error. If the value is greater than zero, the script is executed.

In line 2, we get the user-supplied tax rate. Line 3 multiples the subTotal value times the taxRate.amount value and rounds off the result to two decimal places.

We created two fields for calculating a subtotal. One field is the sum of the Item Total fields, and the other field is the same value less a discount amount. We used the subtotal (or discount) amount for calculating a shipping fee and sales tax.

The Sub Total field sums the data in the Item Total column. The Less Discount field is the Sub Total less 15 percent for an amount exceeding $200. If the amount is less than $200, we use the Sub Total value to calculate the shipping fee and sales tax. If the amount is equal to or greater than $200, we use the Less Discount field to calculate the shipping fee and sales tax.

The three check box fields in the Shipping area of the form contain the JavaScripts for calculating the shipping fee. We used rates based on the total purchase price (from either the Sub Total field or the Less Discount field) to determine the shipping fee. The three check boxes are mutually exclusive fields with separate JavaScripts to calculate the shipping fee.

Using the productOrder.pdf file from the Chapter18 folder on the book's CD-ROM, we add three different scripts to the check box fields for calculating a shipping fee. To understand how to create the calculations, follow these steps.

STEPS: Calculating a Shipping Fee

Figure 18.10. Type the JavaScript in the JavaScript Editor.

In lines 1 to 3, we assign the variables. We need the Sub Total and Less Discount fields used in this calculation. If the Sub Total field is less than 200 (line 5), we use the subTotal value. If the amount is 200 or more, we use the discount value to calculate the shipping fee.

The shipping fee is calculated as 24 percent of the total value (line 6 or line 8 depending on the total purchase price).

For the next check box, we copied the script from the first check box and pasted it into the JavaScript Editor we opened from the second check box field. The only change needed is the fixed rate (.24). We changed this value to .18. In the third check box, we changed the rate to .12.

When the form recipient completes the form, clicking a check box shows the amount of shipping costs. Click a second check box, and the shipping cost changes to reflect the respective calculation. This way, a form recipient can view how much one shipping method varies from another before clicking the submit button.

On the productOrder.pdf form, we added a field above the identifying information fields and named the field orderDate.fld, as shown in Figure 18.12. We set the field properties to Read Only and Hidden in the General field properties window. We formatted the field as None in the Format tab.

Figure 18.12. We added a field to the purchaseOrder.pdf form and named the field orderDate.fld.

Using JavaScript, you can add the current time based on the computer system clock to populate the field as well as add a title such as Date:. If you set the field properties to Read Only, the field cannot be edited if the file is secured after the field is shown on the form.

To add a date stamp to a form, follow these steps.

STEPS: Date Stamping a Form

The script shown in Figure 18.13 is a simple three-line code script. We assign variable f to the field where we want to add a new date. We show the field in line 2, and we add the date in line 3. After clicking the button to add a date, the form appears as shown in Figure 18.14.

Figure 18.14. After clicking the Submit button, the date from the system clock is added to a field and the field as made visible.

The purchaseOrder.pdf form we used in several examples in this chapter contains a combo box field at the top of the form, as shown in Figure 18.15. In this example, when the form recipient chooses an approved vendor from the combo box list the vendor name is added to the Company field appearing below the combo box.

We could add addresses in a JavaScript so when a vendor is selected, not only the vendor name is added to the Company field, but all the identifying information shown in Figure 18.15 is also added. We kept it simple to illustrate a point here, so we didn't add the additional information. For now, just be aware that additional lines of code can populate the remaining fields in this section on the form.

Figure 18.15. A form with a combo box is used to add a name to a text field.

The combo box has a default value of Choose a vendor. For the Company field, you'll notice in Figure 18.15 that nothing appears in this field. The reason for this is that we added a null value to the Company field if the combo box value is Choose a vendor. Here's how we do it.

STEPS: Adding a Null Value to a Field

Figure 18.16. Type the code in the JavaScript Editor.

In the first line of code, we assign variable f to the combo box field. The default value for the field is Choose a vendor. In line 2, we set up an if condition. If the value of the combo box field is not Choose a vendor, line 3 in the script is executed where we get the value of the combo box and place it in the field where this script is written (the vendor.company field).

If the f.value is Choose a vendor, line 5 is executed. We place the value "" (a null value) in the field. If any item in the combo box other than the default value is chosen, the value shown in the combo box is added to the Company field, as shown in Figure 18.17.

Figure 18.17. If the form recipient selects any item other than the default value, the respective item is added to the Company field.

A similar kind of script is used for eliminating zeros from calculated fields. You can handle this in a number of ways. You can add a custom format script in the Format tab, add a script in the Calculate tab, or add a Function at the document level and call the function from a format script. What you do, where you put it, and for what type of fields are important to know.

If you have a form that contains an integer, something like a quantity field, you format the field differently than when you format a field containing a calculation, something like (quantify * amount). As an example, look at the table in the purchaseOrder.pdf form we've worked with in this chapter and shown in Figure 18.18.

Notice that all the fields are empty and devoid of default zeros. In the Qty column, we use a custom format script to eliminate the zeros. In the Each, Item Total, and calculation fields at the bottom of the form, we add some code to the calculation formulas to eliminate zeros.

Figure 18.18. The table is shown from the purchaseOrder.pdf form.

Why do we have two formatting controls on this form? The reason is that the Qty fields are not calculated, so we cannot use a calculation script on these fields. When we add a custom format script to the fields, we're not formatting the fields for a number. In the remaining fields, we definitely need to format the fields as a number. If we do, we cannot add a custom format script in the Format tab. The Format tab permits only format fields using either a custom script or number formatting.

To make this clearer, follow these steps to add both formulas to the form.

STEPS: Eliminating Zeros Using Format and Calculation Scripts

Figure 18.20. Type the JavaScript code for the amount.0 field.

In the first script, we set the formatting for a non-calculated field having an integer value. If a formatted number needed to be added to this field, we couldn't use the format scripts used in the first set of JavaScripts.

In the second script, we look at the first field in the Quantity column (qty.0). If the value is zero, a null value is placed in the each.0 field. We cannot use the same script for the qty.0 field because we need to format the each.0 field as a number with two decimal places.

In the third script for the amount.0 field, we have similar conditions as the each.0 field. This field also needs to have the field formatted as a number. Therefore, we add the script in the Calculate tab to look at the qty.0 field. If the value is not zero, we execute a calculation formula to multiple qty.0 times each.0. If the value f is zero, we add a null value to the amount.0 field.

Unfortunately, the scripts you write for the Each column fields and the Item Total fields require you to add scripts individually to each field. You need to open the field's properties for each field in the respective rows (each.1, each.2, amount.1, amount.2) and add a JavaScript in the JavaScript Editor.

Up to this point, we've dealt with scripts having fewer than ten lines of code. Simple scripts are easy to review and understand. However, when you write a substantial amount of code, when you plan to come back later to the scripts, or when other forms authors work with the forms, you'll want to add comments within the code to understand the routines.

We haven't added notes to the code in this chapter to try to keep the amount of text down so you can easily duplicate the routines. However, in the real world when you add JavaScripts to fields and functions, you'll want to make a habit out of adding programmer's comments.

To add comments to JavaScript code, you add two forward slashes where you want a comment to appear in the code such as:

// This routine calculates sales tax.

Or add code to a line such as:

var f = this.getField("tax"); //get the text field

When a routine is executed, the lines of code following // are ignored by JavaScript.

On the form shown in Figure 18.21, we created three separate functions. You can use multiple functions in a single script, but we broke this example down to three scripts to make it a bit easier to follow.

For the combo box fields on the productOrder.pdf file, we created two functions for formatting the fields. We also needed a third function for the Item Total fields.

Preceding the first function, we set up an array for the combo box fields. We opened the JavaScript Functions dialog box by choosing Advanced

1. var oArray = {
   Book: [ ["-","None"], ["How to Make a Million",99.95],
   ["Investing Wisely",69.95], ["Playing the Market",29.95],
   ["Investing in Bonds",34.95]],
2. Tape: [ ["-","None"], ["Stocks Investing",69.95], ["Bonds
   Investing",49.95], ["Commodities Investing",79.95],["Property
   Investing",139.95]],
3. Video:  [ ["-","None"], ["Global Annual Investment Fest",149.95],
   ["Investing Wisely",159.95], ["Playing the Market",219.95],
   ["Staying Ahead of Inflation",139.95]],
4. Tips:[ ["-","None"], ["Gold",39.95], ["Silver",29.95], ["Orange
   Juice",19.95],["Coffee",9.95]]
5. };
6. function SetDescriptionEntries()
7. {
8.   if(event.willCommit)
9.   {
10.    var cRowName = event.target.name.split(".").shift();
11.    var list = oArray[event.value];
12.    if( (list != null) && (list.length > 0) )
13.      this.getField(cRowName + ".Description").setItems(list);
14.    else
15.   {
16.    this.getField(cRowName + ".Description").clearItems();
17.   }
18.   this.getField(cRowName + ".Each").value = 0;
19.   }
20. }

With 20 lines of code, you obviously want to add some programmer's comments if you create a script like this. We show you just the lines of code that are executed without any notation to simplify the demonstration.

In lines 1 through 4, we set up an array. The first item in each of the four lines of code is the name that appears in the first combo box fields. Therefore, the first combo box contains Book, Tape, Video, and Tips. Making a choice from the first combo box provides the options respective to the item you choose in the second combo box in the Description column. For example, if you choose Book in the Item combo box field in row one, the combo box for the Description row 1 options are "How to Make a Million", 99.95, "Investing Wisely", 69.95, and so on. The value after the name is the price that is placed in the Each column.

In line 6, we added a function named SetDescriptionEntries(). In line 10, we split the name of the field so we can use a loop to loop through the items beginning in line 11. Field names were added such as Row1.Item, Row2.Item, Row3.Item, and so on. Because the names aren't hierarchical, we needed to split the name to gain access to the number following Row for each field.

In line 12, we set the value of the Each column to zero to clear out any data that may have been there from another choice.

The second function we added was named addDescription for the Script Name in the JavaScript Functions dialog box, and we used SetEachValue() for the function name. This function sets the value for the Each column and was written as follows:

1. function SetEachValue()
2.   {
3.     if(!event.willCommit)
4.     {
5.       var cRowName = event.target.name.split(".").shift();
6.       var nSelection = 0;
7.       if(!isNaN(event.changeEx))
8.       nSelection = event.changeEx
9.       this.getField(cRowName + ".Each").value = nSelection;
10.    }
11.  }

This script is set up to run using the Change Event of the previous function. It will not run on other events because the event.willCommit and event.changeEx parameters are used.

The third function we named calculateTotal in the JavaScript Functions dialog box, and we used CalculateTotal() for the function name. We use this function to calculate the totals for the Item Total column. The script was written as:

1. function CalculateTotal()
2.   {
3.     var cRowName = event.target.name.split(".").shift();
4.     event.value = this.getField(cRowName + ".Each").value * this.getField(cRowName + ".Qty").value;
5.   }

The code for the functions is contained in three separate document-level JavaScripts. Rather than analyze the code here, you can open the Advanced

Formatting the fields is easy after you add the functions. For the Item fields, we added a Custom Keystroke Script in the Format tab and used the first function name. The code was written as:

SetDescriptionEntries();

The second field to format is the second combo box fields in the Description column. Again, a Custom keystroke Script was added in the Format properties. The Script was written as:

SetEachValue();

The last field where we used a function was the Item Total fields. We opened the Calculate tab on the fields in the Item Total column and added the following code as a Custom calculation script:

CalculateTotal();

Obviously, writing the functions is much more complex than the other scripts we've discussed in this chapter. It will take a bit of doing to duplicate the scripts on another form, especially if you're a novice programmer. You can copy the Item, Description, Each, Quantity, and Item Total Fields and the document-level JavaScripts and paste into a new form. Everything will work if you leave the field names and code unmodified.

The one item you can change is the array names. Just be certain to use the same syntax when you change the names. After you get some experience and study the scripts, you can begin to change variable names and values.