This article will get you started writing PDF form calculation scripts. We'll cover each of the parts of a basic calculation script in detail, and discuss how it can be expanded into more complicated calculations.
First, you'll need Acrobat Professional to perform this task. Entering calculation scripts, and all other PDF form editing can only be done in Acrobat Professional or another advanced PDF editing tool.
Next, you'll need to know how to get to the Field Properties Dialog, which is where the calculation script is entered. This part of the process is covered in the Entering Calculation Scripts article.
You'll also find some basic information on calculation scripts on the Calculation Scripts page on this site, which you might have already read through to get to this page.
// Acquire Inputs var nA = Number(this.getField("InputA").valueAsString); var nB = Number(this.getField("InputB").valueAsString); // Perform Calculation var nSum = nA + nB; // Assign Result to Field event.value = nSum;
This calculation is so simple that it could easily be done in a single line of code. However, not only is it instructive to explicitly show the individual parts, but these parts need to be separate for more complicated calculations.
Also, while the calculation is simple, there is actually a lot going on here. Let's examine the script more closely.
Generally, the values used in a PDF form calculation are acquired from other form fields. There are other places where data can be acquired, but let's stick with the simplest case. For this script the data is acquired from two fields. One field is named InputA and the other is named InputB . We're not going to get deep into the details of JavaScript coding, but we are going to have to cover a few things. The important part to know here, is that the code - this.getField("InputA").valueAsString , returns the value of the InputA field as a text string. When you use it in your own scripts be careful to make sure the name of your particular field is enclosed in quotes.
It is important to note that this part of the script will fail if field names in the script do not exactly match the field names on the form, including upper case letters. Field naming is a topic all by itself and is very important when dealing with complicated forms and calculations. You can find out more about field naming on the PDF Form Scripting page.
We could have also used the code - this.getField("InputA").value , and you'll see this done quite often in Acrobat scripts. However, the value property is unpredictable in what it returns, the valueAsString property gives us a known type, which is helpful if the field contains a blank.
But of course, what we really need is a number, because we're doing a numeric calculation. So the next piece of code to understand is the Number() function, which converts text into a number. JavaScript is a bit squirrely when it comes to adding numbers and text. If two text values are added together, the result would be the concatenation of the two text values, rather than the addition of two numbers.
For example:
"1" + "1" // Results in the text "11" 1 + 1 // Results in the number 2
It's always best to be explicit with data typing to avoid confusion, which is what the Number() function does, it ensures the calculation is using numbers.
The last piece of code in this section is the variable declaration, var nA . In any programming language a variable is a data container. The declaration statement var creates the container. Then data is assigned to it using the " InputA").valueAsString);
This entire line of code creates a variable named nA and assigns it the numerical value that is in the InputA field.
Notice that I've chosen a particular notation for the variable name. It begins with the lower case letter "n". The "n" stands for Number. Whenever I create variables I always prefix them with a type notation. This is important for being able to understand how a particular variable fits into a script. The script here is so short it doesn't really matter, but this naming prefix is critical for writing long and complex scripts.
One more note on acquiring data. It is very often the case the data needs to be tested before it is used in a calculation. For example, in the case where a value is used in a division, an input of zero cannot be used as a divisor. Or, in date calculations, an input value must be a legal data value. And, there are many more such cases. Data should be tested at the time it is acquired, however data testing is outside the scope of this article.
Now that the data has been acquired it can be used in a calculation. The calculation here is very simple. The values are added together and assigned to a variable named nSum . But the calculation could be different or much more complicated. Here are 4 basic math operators.
var nSum = nA + nB; // Addition var nDiff = nA - nB; // Subtraction var nProd = nA * nB; // Multiplication var nQuot = nA / nB; // Division
var nResult = (nA + 2)/(3*(nB - 4));
Notice that parentheses are used to group individual operations within the complete calculation. These groups are important for ensuring the calculation is done properly. While the parentheses are not always strictly necessary, using them ensures the calculation is always executed properly, and that it can be read and understood by someone else.
Higher math operations such as trigonometric function, exponents, logarithms, etc. are made available through the Math object. For example:
var nResult = Math.sin(nA) + Math.cos(nB);
event.value = nSum;
In a calculation script, assignment to the field is always done with event.value . It's done this way because the field is in a transitional state. At the time the calculation is taking place the real field value has not yet changed, but there are more things the field has to do before the new value can be applied to the field. So, event.value is used to store the new value while the field is going through the update process.
Here's what our simple calculation script looks like in a single line of code. Notice that no variable declarations are needed because none of the intermediate steps are broken out.
event.value = Number(this.getField("InputA").valueAsString) + Number(this.getField("InputB").valueAsString);
And that is how you write a simple PDF form field calculation.