Tutorials, tools, scripts and samples for scripting Acrobat and PDFpdfscripting.com
HomeVideo TutorialsCopy-n-Paste ScriptsDownload LibraryFree ContentSearchMEMBERS LOG-IN


About Us
Contact Us
Privacy Policy
Refund Policy
Site Video Tour
Terms of Use
Testimonials
Articles
Video Tutorials
Automating Acrobat
Copy-n-Paste Scripts
Download Library
Free Content
Free Videos

Let me know when new content is available.

Home | AcroForm Calculations
 

Calculating field values and more

Thom Parker

Calculations are one of the most important activities performed by an electronic form. In the simplest instance, a calculation is a mathematical combination of the values from other fields on a form. For example, multiplying the quantity and price entries on an order form to find the cost, or adding all the cost fields together to find the total cost of the order. But of course, there are many different types of calculations that a form might need, and many different ways a calculation might be done. For example, a calculation could depend on whether a check box is marked. This is a conditional calculation. Or, a calculation might be used to add up the number of checked boxes in a table. Or, it might be used for something completely different. There is a lot of variation in calculation scripts.

In an AcroForm (a regular PDF form), field calculations are performed by the Calculation Event Script. This event can be applied to any form field and it's triggered whenever any field on the PDF is modified. But of course, it is most often associated with Text Fields. In fact, Acrobat only provides a user interface for entering calculations into the Text Field and the ComboBox Field. Entering a calculation script into one of the other field types requires the use of a script (see articles below for more info on entering calculation scripts).

The Calculation Event is triggered for every field that has a calculation script every time any field on the form changes. However, field changes made through the official Calculation Event mechanism do not trigger further calculation events. This can be a tricky issue. If a script makes changes to a field outside of the event mechanism then it can cause more calculation events. Obviously, this is not a good situation since there is a possibility of infinite events looping. Also, since calculation events are called frequently, there is a chance they could cause the form to have serious performance issues.

So, there are some rules that should be followed when writing calculation scripts.

  1. Always set the calculated field value with the "event.value" property.
    (Examples shown below in the articles)
  2. Never use the calculate event to set other field values.
    (Unless you know exactly what you are doing))
  3. Keep calculation scripts as short as possible since they are run frequently.
  4. Keep the number of calculation scripts on a form to a minimum.
  5. Never use a Blocking Action in a calculation script. A Blocking Action is any code that stops execution and waits for the user, or something else to respond, such as an alert box.
One of the problems with the calculation script is that it is fired even when the field that's changed is not involved in any calculation. This can become a serious issue if your form has scripts that pre-populate, or act on several fields. Fortunately, the Acrobat JS DOM provides a document property for blocking calculations, "doc.calculate". No calculation scripts will be run when this property is set to false. On the other side, there is also a function for forcing calculations, "doc.calculateNow()". Call this function to force all calculations on the form to be run.

The Calculation Event does not have to be used for calculations. In fact, in a more general sense it's just an event that gets called when a form field changes. So, it can be used to run a script you want triggered any time the form fields change. For example, a form could have its "submit' button initially hidden, and then use the Calculate Event to test certain required fields and only show the submit when they are filled out correctly. This creates a kind of form-level validation. But again, this has to be done with care to prevent performance problems or worse.

For more information see the video tutorials and examples on the Calculation Event


Entering Calculation Scripts
Thom Parker
This article covers the basics of entering Calculation Scripts into a PDF. It is primarily for beginning scripters, but there are also tidbits of interest for intermediate and advanced users. . . . keep reading
Writing Calculation Scripts
Thom Parker
This article covers the rules and techniques for writing AcroForm Calculation Scripts. Several examples are provided to demonstrate the ideas discussed. . . . keep reading
Form Table Calculation Samples
AcroForm, Calculation, Table, LiveCycle,Form
This page lists all the download samples with table calculations, as well as a short discussion on how to write table calculations. . . . keep reading
Form Level Validation - Strategies
Thom Parker
Form level validation is used to ensure all the required form data is filled in, and/or to make sure any data dependencies between fields are met before the form is submitted, saved, printed, or emailed. . . . keep reading
Counting Text items: Characters, Words and Lines
Thom Parker
There are many commercial applications (press releases, product descriptions, ad text, etc.) as well as others where counting text elements like characters and words is important. The scripts on this page provide several different techniques for finding this information, including filtering text for specific characters and words. . . . keep reading
Counting Fields: CheckBoxes, RadioButtons, Filled/Empty Fields, and Others.
Thom Parker
It's often important to count data entries on a form. For example, for an average calculation the number of filled fields needs to be counted. Or, to score a test the number of checked Radio Buttons may need to be counted. This short article covers different techniques for building calculation scripts that count stuff. . . . keep reading
AcroForm Calculation Examples
Thom Parker
This page is a listing of sample PDFs that use the calculation event. The samples are collected from different areas of this site. They are not necessarily "Calculation" examples, but they all u . . . keep reading
Date and Time Calculations
Thom Parker
Several common date calculations, including finding age, the number of days and hours between two dates, calculating expiration dates, and many others. . . . keep reading