|
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.
- Always set the calculated field value with the "event.value" property.
(Examples shown below in the articles)
- Never use the calculate event to set other field values.
(Unless you know exactly what you are doing))
- Keep calculation scripts as short as possible since they are run frequently.
- Keep the number of calculation scripts on a form to a minimum.
- 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
|
About Us
