bc

LiveCycle® Designer ES2 Scripting Basics

Adobe® LiveCycle® Designer ES2

November 2009 Version 9
© 2009 Adobe Systems Incorporated. All rights reserved.
Adobe® LiveCycle® Designer ES2 (9.0) Scripting Basics for Microsoft® Windows®
Edition 4.0, November 2009
This reference guide is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This
License allows users to copy, distribute, and transmit the guide for noncommercial purposes only so long as (1) proper attribution to
Adobe is given as the owner of the guide; and (2) any reuse or distribution of the guide contains a notice that use of the guide is governed
by these terms. The best way to provide notice is to include the following link. To view a copy of this license, visit http://creative-
commons.org/licenses/by-nc-sa/3.0/.
Adobe, Adobe logo, Adobe Reader, Acrobat, and LiveCycle are either registered trademarks or trademarks of Adobe Systems Incorpo-
rated in the United States and/or other countries. Microsoft and Windows are either trademarks or registered trademarks of Microsoft
Corporation in the United States and/or other countries. All other trademarks are the property of their respective owners.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
 3

Contents
About This Document
Who should read this document? .......................................................................................................6
Purpose and scope .....................................................................................................................6
Additional information .................................................................................................................7

1. About scripting in Designer ES2

How scripting works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Objects that support calculations and scripts ...........................................................................................9
Understanding relationships between objects in the Object Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Configuring the Designer ES2 workspace for Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2. Configuring LiveCycle Designer ES2 for Scripting

To show the Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
To change from single-line to multiline view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
To set the default scripting language for new forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
To set the default scripting language for the current form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
To set the default scripting language for a form template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
To set the default processing application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
To display Arabic, Hebrew, Thai, and Vietnamese characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Using the workspace to debug calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3. Creating Calculations and Scripts

Making scripts global by using event propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
To enable event propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Naming conventions for form design objects and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Choosing a scripting language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
To create a calculation or script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
To find text or other items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
To replace text or other items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
To use statement completion to create calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
To insert object reference syntax automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Determining when to run your calculation or script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
To view scripting events and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Determining where to run your calculation or script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Testing and debugging calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
To check script syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Working around security restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4. Events
Types of events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Process events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Interactive events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
 4

Application events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
calculate event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
change event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
click event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
docClose event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
docReady event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
enter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
exit event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
form:ready event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
full event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
indexChange event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
initialize event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
layout:ready event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
mouseDown event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
mouseEnter event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
mouseExit event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
mouseUp event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
postOpen event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
postPrint event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
postSave event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
postSign event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
postSubmit event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
preOpen event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
prePrint event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
preSave event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
preSign event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
preSubmit event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
validate event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

5. Scripting with FormCalc and JavaScript

Using FormCalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Using built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
To attach a FormCalc function to an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Built-in function syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Creating basic calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Using JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Creating scripts using JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Enforcing strict scoping rules in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
To attach a JavaScript script to an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

6. Variables
Naming variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
To define a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
To view a text variable definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
To delete a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
 5

Using variables in calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

7. Referencing Objects in Calculations and Scripts

Referencing object properties and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Referencing unnamed and repeated objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Referencing the current object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
FormCalc reference syntax shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

8. Creating and Reusing JavaScript Functions

To create a script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
To reference JavaScript functions stored in a script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

9. Using Script Fragments

Script fragment properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
To create a script fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
To insert a script fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

10. Debugging Calculations and Scripts

JavaScript Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Debugging tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

11. Working with a Host Application

12. Working with the Event Model

13. Moving from Scripting in Acrobat to Designer ES2

Converting Acrobat forms that contain scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Using JavaScript objects from Acrobat in Designer ES2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
JavaScript objects from Acrobat supported in Designer ES2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

14. Examples of Common Scripting Tasks

Changing the background colors of fields, fillable areas, and subforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Hiding and showing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Excluding an object from the tabbing order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Changing the visual properties of an object on the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Getting the current or previous value of a drop-down list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Preserving rich text formatting when copying field values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Adjusting the height of a field at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Setting a field as required at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Calculating the field sums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Highlighting fields in response to form filler interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Resetting the values of the current subform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Changing the presence of a form design object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Using the properties of the instance manager to control subforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Using the methods of the instance manager to control subforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Using the instance manager to control subforms at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
 6

About This Document

Welcome to Adobe® LiveCycle® Designer ES Scripting Basics. This scripting document is designed to provide you with an overview of how
you can use Designer ES2 calculations and scripts to develop and enhance forms created in Designer ES2. For example, you can use calcu-
lations and scripts to perform the following actions:
• Change the behavior and appearance of objects at run time
• Control the presentation of field values
• Provide interaction with form fillers using dialog boxes and visual cues
• Automate form filling
• Control the hosting environment
• Interact with web services
• Interacting with databases and populate forms with data from data sources
Here you will find detailed information and examples of what the Designer ES2 calculation and scripting capabilities are and how to access
them, as well as descriptions of the usage of the Designer ES2 Script Editor. Designer ES2 calculations and scripts are a powerful way to
enhance and extend your Designer ES2 forms.

Who should read this document?

This guide is intended for form authors and form developers interested in using calculations and scripts to extend their Designer ES2 forms.
However, it is assumed that you have a working knowledge of scripting languages, especially JavaScript™, as well as object models. You should
also be familiar with Adobe Acrobat® Professional or Acrobat Standard and be comfortable working in a structured XML environment.

Purpose and scope

The purpose of this guide is to provide you the following information:
• An introduction to using Designer ES2 calculations and scripts to extend your forms
• Easily understood, detailed information and examples of the Designer ES2 calculation and scripting features
• References to other resources where you can learn more about Designer ES2 scripting and related technologies
After reading this guide, you should be equipped to start using Designer ES2 calculations and scripts. During the development process, you
will find that the descriptions and examples in this guide will provide you with enough direction and background to enable you to success-
fully complete your projects.
 LIVECYCLE DESIGNER ES2 7
About This Document LiveCycle Designer ES2 Scripting Basics

Additional information
Adobe has a wide variety of resources dedicated to Designer ES2 scripting focused at both the form author and the form developer
audiences. The following illustration and section outline the different resources available and where to find them.

Designer ES2 Help

Designer ES2 Help contains detailed information about using the product, including information on using calculations and scripts, and
should be the first place you search for information on any topics related to Designer ES2. You can access Designer ES2 Help from the Help
menu when Designer ES2 is installed, or online at http://www.adobe.com/go/learn_lc_designer_9.

Designer ES2 Scripting Basics guide

This guide provides an overview of creating calculations and scripts for use with Designer ES2. This guide is intended to help you create
calculations and scripts using FormCalc and JavaScript.

Articles and reference library

The Designer ES2 Scripting Reference is a detailed reference of the models, objects, properties, and methods that you can use with
Designer ES2. This PDF is intended as reference material only; it is not intended to give users information on how to create calculations or
scripts. See Designer ES2 Scripting Reference.

User Forums
The Designer ES2 Forum is a meeting place for professionals who are interested in discussing issues related to Designer ES2. Respond to
reader questions, report bugs or issues with the product, or post questions of your own to other form designers and Adobe experts. For infor-
mation, see www.adobeforums.com.
 LIVECYCLE DESIGNER ES2 8
About This Document LiveCycle Designer ES2 Scripting Basics

Scripting samples
The scripting samples are working forms or packages that include instructions on how the sample was created and any sample data used to
create and view the form. New samples are added on an ongoing basis by both Adobe experts and third-party organizations. See the samples
at www.adobe.com/devnet/livecycle/samples.html.
 9

1. About scripting in Designer ES2

As part of the form design process, a form developer can use calculations and scripts to provide a richer user experience. You can add calcu-
lations and scripts to most form fields and objects. For example, the following JavaScript script multiplies the values of two numeric fields
together and displays the result in a third numeric field:
NumericField3.rawValue = NumericField1.rawValue * NumericField2.rawValue;

At a more advanced level, you can create your own functions tailored towards your own custom form processing needs.
Designer ES2 supports two scripting languages, each geared towards the needs of a particular type of form developer. FormCalc is a straight-
forward, easy-to-use calculation language that is modelled on common spreadsheet functionality. It includes a variety of built-in functions
designed to reduce the amount of time you need to spend developing your form design. JavaScript, a powerful scripting language, provides
you with a great deal of flexibility when creating your scripts and allows you to leverage any existing knowledge of the language.
Remember that scripting on a form is entirely optional. You can choose to take advantage of scripting to provide a richer user experience,
but many of the most powerful features available during form creation are available in Designer ES2 without the use of scripts. However,
through scripting, you can manipulate and control almost all aspects of your form design.
Note: You can also use the Action Builder dialog box on the Tools menu to build common interactive capabilities in forms that have a flowable
layout, without writing scripts.

How scripting works

Designer ES2 scripting uses an event-based model that allows you to alter various aspects of objects on a form at run time. As a form
designer, you add scripts to objects based on when you want the script to execute. For example, you might place the following script on the
click event of a button object so that at run time, when a user clicks the button, a message box appears with a message:

xfa.host.messageBox("This is a message for a form filler.", "User Feedback", 3);

Scripts associated with a particular event execute whenever that event occurs. Some events can occur multiple times within the same form
filling session. For example, the following script adds one to the current value of a numeric field:
NumericField1.rawValue = NumericField1.rawValue + 1;

If you add this script to the calculate event for NumericField1, when you open the form for the first time, NumericField1 displays the
value 2. This indicates that the calculate event occurred twice in the sequence of events that occurred when the form was opened.

Objects that support calculations and scripts

The following table provides a quick reference of scripting support for the standard objects that are included in the Library palette in
Designer ES2.

Objects that support calculations and scripts Objects that do not support calculations and scripts

Barcodes Circle

Button Content Area

Check Box Line

Date/Time Field Rectangle

Decimal Field Image

Signature Field Subform Sets

 LIVECYCLE DESIGNER ES2 10
About scripting in Designer ES2 LiveCycle Designer ES2 Scripting Basics

Objects that support calculations and scripts Objects that do not support calculations and scripts

Drop-Down List Table sections

Email Submit Button Text

HTTP Submit Button

Image Field

List Box

Numeric Field

Paper Forms Barcode

Password Field

Print Button

Radio Button

Reset Button

Subform

Table (including body rows, header rows, and footer rows)

Text Field

Understanding relationships between objects in the Object Library

When you create calculations and scripts in Designer ES2, you should be aware that the objects on which you are adding scripts are actually
defined as XML objects in the underlying XML Forms Architecture. That means while the Standard tab of the Object Library palette
contains a wide variety of objects, many of those objects are defined by the same XML object. As a result, the various scripting properties
and methods that are available are based on the definition of the XML object, and not the object in the Object Library palette.
Objects available in the Standard tab of the Object Library palette that are based on the same base XML object definition share a set of
common properties and methods. If you are referring to the Designer ES2 Scripting Reference, you determine the set of properties and
methods available based on the corresponding base XML object. Similarly, each base XML object definition contains a child object that
specifically controls the visual appearance of the Designer ES2 object.
For example, if you want to browse the properties and methods that are available for a Date/Time Field object in Designer ES2, you would
start with the field object. If you want to browse the corresponding XML object that controls the visual appearance of the Date/Time Field,
view the dateTimeEdit object.
The table below illustrates the mapping between objects that you see in the Standard tab of the Object Library palette in Designer ES2, and
the corresponding XML Form Architecture object.

Standard Object Library Object XML Form Architecture Object (Base) XML Form Architecture Object (UI)

Barcodes field barcode

Button field button

Check Box field checkButton

Date/Time Field field dateTimeEdit

Decimal Field field numericEdit

Signature Field field signature

 LIVECYCLE DESIGNER ES2 11
About scripting in Designer ES2 LiveCycle Designer ES2 Scripting Basics

Standard Object Library Object XML Form Architecture Object (Base) XML Form Architecture Object (UI)

Drop-Down List field choiceList

Email Submit Button field button

HTTP Submit Button field button

Image Field field imageEdit

List Box field choiceList

Numeric Field field numericEdit

Paper Forms Barcode field barcode

Password Field field passwordEdit

Print Button field button

Radio Button field checkButton

Reset Button field button

Subform subform N/a

Table (including body rows, header rows, and subform N/a

footer rows)

Text Field field textEdit

Configuring the Designer ES2 workspace for Scripting

The Script Editor is where you create, modify, and view the calculations and scripts of a particular form. For example, you can use the Script
Editor to write a simple calculation that adds two numeric fields or complex scripts that alter the appearance of the form based on end-user
actions. Designer ES2 supports scripting either in its own scripting language called FormCalc or in JavaScript.
By default, the Script Editor appears at the top of the Designer ES2 workspace, but you can dock it anywhere. It has both a single-line view
and a multiline view that you can switch between, depending on your needs. Single-line view is designed to maximize the amount of space
dedicated to the Layout Editor and other palettes. Multiline view is designed to maximize the amount of space for writing script.

Single-line view: A. Script editing field

Multiline view: A. Reference syntax B. Show Events for Child Object button C. Functions button D. Check Script Syntax button E. Script editing field

Show Lists all form design events that support user-defined scripting. Any events that do not apply to a particular object appear dimmed.
Events that contain a calculation or script display an asterisk (*) beside the name of the event.
 LIVECYCLE DESIGNER ES2 12
About scripting in Designer ES2 LiveCycle Designer ES2 Scripting Basics

Show Events for Child Objects Displays the event you have currently selected in the Show list for the current object and all of its child
objects. If you select the uppermost object in the Hierarchy palette, this option displays the event you have currently selected in the Show
list for all objects on your form.
Functions Displays a list of available built-in FormCalc or JavaScript functions, depending on the scripting language you currently
have selected in the Language list.
To place a function onto your script editing field, select a function from the list and press Enter.
Check Script Syntax Checks all of the scripts in a form for correct syntax and reports any errors on the Warnings tab in the Report
palette.
Language Specifies the scripting language you want to use for the current calculation or script. Two options are available:

• FormCalc FormCalc is a native Adobe calculation language typically used for shorter scripts, such as simple calculations.
• JavaScript JavaScript is the default scripting language for new forms.
The scripting language that is displayed in the Language list matches the scripting language option you select as the default for new forms
in the Workspace panel in the Options dialog box. However, if you change the scripting language setting for the current form on the
Defaults tab in the Form Properties dialog box, the scripting language that is displayed in the Language list changes similarly for any
new scripts on new events. Changing the scripting language option in the Form Properties dialog box does not change the scripting
language for existing scripts. If an event already contains script and that script is deleted, the Script Editor continues to use that same
scripting language for the duration of your Designer ES2 working session.
See “To set the default scripting language for new forms” on page 13
Run At Specifies where the calculation or script will execute. Three options are available:

• Client Calculations and scripts execute while the client application (for example, Acrobat, Adobe Reader, or a web browser)
processes the form.
• Server Calculations and scripts execute while the server application (for example, Forms ES2) processes the form.
• Client and server Calculations and scripts execute while the server application (for example, Forms ES2) processes the form, except
in cases where the HTML client application supports client-side scripting. For example, a script that accesses a database to prefill
data on a form.
Enable Event Propagation Specifies that form events propagate to ancestor containers.
 13

2. Configuring LiveCycle Designer ES2 for

Scripting
To show the Script Editor
❖ Select Window > Script Editor.
Note: You can use the Expand button to quickly dock or undock the Script Editor when it is displayed in the Designer ES2 workspace.

To change from single-line to multiline view

❖ Drag the Script Editor palette bar until the palette is the required size.
Note: Multiline view adds the All Events and Events with Scripts options to the Show list. The All Events option displays all of the events for
a particular form design object, even if the events do not contain any calculations or scripts. The Events with Scripts option displays only
those events of a particular object that contain calculations or scripts.

To set the default scripting language for new forms

1 Select Tools > Options.
2 Click Workspace.
3 In the Default Language For New Forms list, select the default scripting language for new forms.

To set the default scripting language for the current form

1 Select File > Form Properties.
2 Click the Defaults tab.
3 In the Default Language list, select the default scripting language for the currently displayed form.

To set the default scripting language for a form template

1 Create a new form design.
2 Select File > Form Properties.
3 Click the Defaults tab.
4 Select your default scripting language from the Default Language list.
5 Make a backup of the original form template file located in the Templates folder where Designer ES2 is installed.
6 Save the new form design as a TDS file and overwrite the corresponding form template. For example, save the file as Letter.tds and
overwrite the Letter.tds file located in Templates\Blank folder.

To set the default processing application

1 Select File > Form Properties.
2 Click the Defaults tab.
3 Select your default processing application from the Default Run At list.
Note: This procedure only sets the value of the default processing application for the current instance of the form.
To avoid changing the default processing application each time you create a form, you must modify the corresponding form template
file that is used to create a new form design.
 LIVECYCLE DESIGNER ES2 14
Configuring LiveCycle Designer ES2 for Scripting LiveCycle Designer ES2 Scripting Basics

To change the default processing application for a form template

1 Create a new form design.
2 Select File > Form Properties.
3 Click the Defaults tab.
4 Select your default processing application from the Default Run At list.
5 Make a backup of the original form template file located in the Templates folder where Designer ES2 is installed.
6 Save the new form design as a TDS file and overwrite the corresponding form template. For example, save the file as Letter.tds and
overwrite the Letter.tds file located in Templates\Blank folder.

To display Arabic, Hebrew, Thai, and Vietnamese characters

To display Arabic, Hebrew, Thai, and Vietnamese characters in the Script Editor or XML Source tab, you must change the font settings that
Designer ES2 uses in these tabs. Otherwise, Designer ES2 displays rectangles where the language-specific characters should be.
1 Select Tools > Options and select Workspace from the list on the left.
2 Select one of the following options:
• FormCalc Syntax Formatting to set the font in the Script Editor when you use FormCalc
• JavaScript Syntax Formatting to set the font in the Script Editor when you use JavaScript
• XML Source Syntax Formatting to set the font in the XML Source tab
3 In the Font box, select a font that supports your language. For example, Adobe Arabic supports Arabic, Adobe Hebrew supports Hebrew,
Adobe Thai supports Thai, and Myriad® Pro and Minion® Pro support Vietnamese. You can locate the font you need for your language
on the Internet if it is not already on your system.
4 Click OK.
5 Click OK to close the Options dialog box.

Using the workspace to debug calculations and scripts

The Designer ES2 workspace provides a number of ways to assist you with debugging your calculations and scripts.
The following table provides the location and purpose of some helpful debugging information located on various Designer ES2 palettes and
tabs.

Workspace location Purpose

Warnings tab in the Report palette Displays target and warning marker messages as well as all JavaScript or FormCalc scripting syntax errors when you select
the Check Script Syntax command from the Tools menu or click the Check Script Syntax button in the Tools toolbar. For more
information, see “To check script syntax” on page 22.

When you double-click a syntax warning message in the Warnings tab, the script that contains the error is loaded into the
Script Editor, and the line with the error is highlighted.

You can also double-click a warning message to select the related object in the Design View and the Hierarchy palette, and
press F1 to display information about how to fix the warnings.

To check for JavaScript run-time errors, you can activate the JavaScript Console. For more information, see “JavaScript
Debugger in Acrobat Professional” on page 71.

Binding tab in the Report palette If you include fields on your form design that are bound to a data source, the Binding tab can assist you by displaying lists
of fields based on how you defined their data binding. For example, you can list only fields with Global Data Binding or only
those with no data binding defined. This feature is especially useful on forms that have a large number of data bound fields.

Log tab in the Report palette Displays validation messages, JavaScript or FormCalc scripting execution errors, and design-time form rendering errors
generated by Designer ES2 when you import or save a form, or preview a form using the Preview PDF tab.
 LIVECYCLE DESIGNER ES2 15
Configuring LiveCycle Designer ES2 for Scripting LiveCycle Designer ES2 Scripting Basics

Workspace location Purpose

Hierarchy palette You can use the Hierarchy palette to determine the location of a form object for a reference syntax. The Hierarchy palette is
a graphical representation of the structure of a form. It displays the contents of the Master Pages and Design View tabs.

The Hierarchy palette also displays referenced objects under the Referenced Objects node. A referenced object is an object
that is added to a form only when it is required. Whenever data flows across multiple pages or content areas, the overflow
leader and trailer subforms are inserted into the form in the appropriate places.

Binding tab in the Object palette Every Designer ES2 object that can be bound to a data source includes a Binding tab in the Object palette. If you bind an
object on your form design to a particular data node from your data connection, the Data Binding (Open, Save, Submit) list
displays a valid FormCalc reference syntax for accessing that data node. You can use the FormCalc reference syntax in other
calculations or scripts for testing purposes.

XML Source tab The XML Source tab contains the form design’s XML code. The XML source code defines all aspects of the form. You can use
the XML Source tab to view the XML Form Object Model structure of a form design and to understand the relationships
between objects and properties. In the XML source, the XML element names are equivalent to the object names in the XML
Form Object Model, and attributes are equivalent to properties.

When you select an object in the Hierarchy palette and then click the XML Source tab, the first line of the corresponding
element is highlighted. The object name in Designer ES2, as listed in the Hierarchy palette, becomes the value of the name
attribute in the XML source.

You can set options in the Tools > Options dialog box for viewing the source in the XML Source tab, such as showing or
hiding line numbers and setting the syntax coloring.

It is recommended that you do not edit the XML source code directly.

You may also find it useful to change the default options for the Script Editor to make it easier to debug your calculations and scripts. These
options are in the Workspace panel of the Options dialog box, which is available by selecting Tools > Options and then selecting Workspace
from the list on the left. For example, you can choose to display line numbers in the Script Editor or change the formatting of FormCalc or
JavaScript syntax.
“Creating Calculations and Scripts” on page 16
“Events” on page 24
“Debugging Calculations and Scripts” on page 70
 16

3. Creating Calculations and Scripts

Designer ES2 provides a wide range of calculation and scripting features that you can use to perform a variety of tasks. For example, the
following script changes the color of a text field border and the font size of the text field value:
TextField1.border.edge.color.value = "255,0,0";
TextField1.font.typeface = "Courier New";

More complex forms can take advantage of scripting to perform data source connectivity and data manipulation at run time. For examples
of common scripting tasks, see “Examples of Common Scripting Tasks” on page 89.
Creating calculations and scripts in Designer ES2 involves following a general process each time you attach a calculation or script to an
object. Although not all aspects of the process are required each time you create a calculation or script, following the process helps to
eliminate potential errors and unexpected results.
In general, each time you create a calculation or script, you perform the following tasks:
• Select the object to which you want to attach a calculation or script. Although you can create calculations and scripts that manipulate
almost any object on your form design, not all form design objects support form events. For a list of standard objects included in the
Object Library palette in Designer ES2 that support scripting, see “Objects that support calculations and scripts” on page 9.
• Write your calculation or script in the script editing field of the Script Editor.
• Test the calculation or script either by using the Preview PDF tab or in your test environment.

Making scripts global by using event propagation

You can make scripts global by enabling event propagation in the Script Editor. The setting allows form events to propagate to ancestor
containers. Event propagation can reduce the number of scripts in a form. For example, you can create a global script to control the
appearance of invalid fields, subforms, or exclusion groups. Here are examples of global events:
• An enter/exit/mouseEnter/mouseExit event that colors the active field
• A change event that track keystrokes for a form session

To enable event propagation

❖ In the Script Editor, select Enable Event Propagation.
Note: Select the object and write the script at the ancestor level before enabling event propagation.

Naming conventions for form design objects and variables

When creating calculations or scripts to enhance your form, be aware of the form design object and variable names on your form. In general,
avoid using the names of XML Form Object Model properties, methods, and objects for form design objects and variables. Using XML Form
Object Model property, method, or object names can result in calculations and scripts not executing properly.
For example, if you create a new text field named x within a subform object named Subform1, you access the text field object using the
following syntax:
Subform1.x.[expression]

However, subform objects already have an XML Form Object Model property named x that represents the horizontal position of the
subform on the form design.
To avoid naming conflicts, you need to choose field naming conventions that differ from the XML Form Object Model naming conventions.
For example, you can use any of the following field names for the text field in the example above:
 LIVECYCLE DESIGNER ES2 17
Creating Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

• horizontalValue
• x_value
• xLetter
• hValue
For more information and a list of the XML Form Object Model property, method, and object names, see LiveCycle Designer Scripting
Reference.

Choosing a scripting language

Designer ES2 supports scripting with both FormCalc and JavaScript. Each scripting language presents its advantages that you should be
aware of before you write any scripts on your form.
FormCalc is a calculation language that includes a wide range of built-in functions to simplify the most common form functionality. For
example, you can use FormCalc financial functions to evaluate the size of a loan payment based on the principle amount, interest rate, and
number of payment periods.
JavaScript is a more powerful and diverse scripting language, intended to give you more flexibility and leverage your existing scripting
knowledge. For example, you can reuse your existing JavaScript functions in Designer ES2 to reduce the amount of new scripting you need
to create.
Note: Designer ES2 supports JavaScript version 1.6 or earlier.
You can choose the scripting language that is used for new forms in the Workspace panel in the Options dialog box, and for the current form
on the Defaults tab in the Form Properties dialog box.
The scripting language that is displayed in the Language list in the Script Editor matches the scripting language option you select as the
default for new forms. However, if you change the scripting language setting for the current form, the scripting language that is displayed in
the Language list changes similarly for new scripts on new events. Changing the scripting language option in the Form Properties dialog box
does not change the scripting language that was used for existing scripts. If an event already contains some script and that script is deleted,
the Script Editor continues to use that scripting language for the duration of your Designer ES2 working session.
The following table highlights some of the key differences between FormCalc and JavaScript.

FormCalc JavaScript

Native Adobe calculation language valid in Designer ES2 and Forms ES2 Standard scripting language used in many popular software applications

Shorter scripts (typically one line only) Potential for longer scripts, if necessary, with the ability to use looping

Supports script looping

Not supported by form guides Supported by form guides

Contains a variety of useful built-in functions to reduce the amount of scripting Provides access to the Acrobat Object Model and the JavaScript capabilities of
required to accomplish common form design tasks Acrobat

Support for international dates, times, currencies, and number formats Debugging possible by using the JavaScript debugger in Acrobat

Built-in URL functions for Post, Put, and Get allow web-based interactions Create custom functions for your own specific needs

Compatible on all Designer ES2 and Forms ES2 supported platforms Compatible on all Designer ES2 and Forms ES2 supported platforms

To create a calculation or script

1 Select an object on your form design that supports events. For example, add a button to a new, blank form.
 LIVECYCLE DESIGNER ES2 18
Creating Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

2 In the Script Editor, from the Show list, select one of the events that apply to the object. The event you choose specifies when the script
will execute. If you are writing a calculation or script that affects an object that does not support events, you must add your calculation
or script to a form design object that does support form events. For example, using the new button object, select the click event in the
Show list.
3 In the Language list, select your scripting language. For example, for the new button object, select JavaScript.
4 In the Run At list, select where you want the script to execute. For example, for the new button object, select Client.
You can choose to run calculations or scripts on your client-based application (for example Acrobat or a web browser) or on your server-
based process (for example, Forms ES2). When set to Client, processing of calculations and scripts initiates after the form renders. When
set to Server, processing of calculations and scripts initiates during the form rendering process. Previewing your form by using the
Preview PDF tab simulates opening the form in Acrobat; therefore, scripts set to run at Client or Client and Server execute.
Note: Selecting Client And Server from the Run At list causes a script to execute in either the client application or the server application,
depending on which application is used to process the form.
5 In the Script Source field, insert your FormCalc calculation or JavaScript script. You can take advantage of the statement completion
functionality of Designer ES2 to help you create reference syntaxes for your calculation or script. For example, add the following JavaS-
cript script to the new button object:
xfa.host.messageBox("Hello World!", "Creating a new script", 3);

6 After you complete your form design, test and debug your calculations and scripts before putting them into production. For example,
for the new button object, preview the PDF of the form using the Preview PDF tab. Click the button object to display the message box
specified in step 5.
For more information about the Designer ES2 objects that support scripting, see “Objects that support calculations and scripts” on
page 9.

To find text or other items

You can quickly search for every occurrence of a specific word or phrase when you are in the XML Source tab or in the Script Editor.
1 In the XML Source tab or the Script Editor, select Edit > Find or right-click for the context menu.
2 In the Find What box, enter the text that you want to search for.
3 Select any other options that you want.
4 Click Find Next.
To cancel a search in progress, press Esc or select the Cancel button.
Caution: Although it is possible to edit XML source code directly in the XML Source tab, it is recommended that you do not make any
changes unless you are familiar with the Adobe XML Forms Architecture. For more information about the XML Forms Architecture, see
www.adobe.com/devnet/livecycle/.

To replace text or other items

You can automatically replace text. For example, you can replace Corp. with Corporation.
1 In the Script Editor, select Edit > Replace.
2 In the Find What box, enter the text that you want to search for.
3 In the Replace With box, enter the replacement text.
4 Select any other options that you want.
5 Click Find Next, Replace, or Replace All.
6 To cancel a search in progress, press Esc or select the Cancel button.
To replace text that appears in scripts attached to multiple objects on your form, select the root subform of your form (by default: form1)
and select Show Events for Child Objects and then perform the procedure above.
 LIVECYCLE DESIGNER ES2 19
Creating Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Caution: Although it is possible to edit XML source code directly in the XML Source tab, it is recommended that you do not make any
changes unless you are familiar with the Adobe XML Forms Architecture. For more information about the XML Forms Architecture, see
www.adobe.com/devnet/livecycle/.

To use statement completion to create calculations and scripts

The statement completion functionality within the Script Editor lets you build your calculations and scripts interactively.
When writing a calculation or script, each time you enter a period (.) immediately following a form object or property name, the statement
completion functionality displays a list of available methods and properties. If the statement completion list does not appear, verify that you
have typed the object or property name correctly and that the object is within the scope of the object where you are creating your script. For
more information about referencing objects in calculations and scripts, see “Referencing Objects in Calculations and Scripts” on page 58.
1 Type the name of a form design object, property, or a valid FormCalc shortcut, followed by a period.

A. Available XML Form Object Model properties B. Information pane

2 Select the method or property you want to apply for the form design object and continue writing the script. To close the statement
completion list without selecting a function, press the Esc key.
The list of available XML Form Object Model properties changes depending on the form design object or property that appears before
the period.
Note: The statement completion list appears only when accessing objects, properties, and methods in the XML Form Object Model. It does
not appear when working with standard JavaScript objects or methods.

To insert object reference syntax automatically

As an alternative to using the statement completion list to create object reference syntax, you can use the insert object reference syntax
feature to automatically add reference syntax to your calculation or script. This feature inputs an abbreviated reference syntax for the object
you select from the canvas into the Script Source field of the Script Editor. This reduces the time required to create calculations and scripts
and ensures that the reference syntax is accurate.
1 Ensure that the Script Source field of the Script Editor has the focus and the cursor is positioned where you want to insert the object
reference.
2 On your form, Ctrl+click the object you want to reference. The cursor changes to to assist you when selecting an object.
 LIVECYCLE DESIGNER ES2 20
Creating Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Determining when to run your calculation or script

When creating calculations and scripts, you must associate each entry with a specific form event. Each form event represents a change in
the form’s state that initiates at a specific time. The change in form state can occur during form rendering on the server by Forms ES2, or on
the client by Acrobat or Adobe Reader while a user is filling a form. When a change in the state of the form occurs, any calculations or scripts
associated with the event are processed automatically.
The event you use when creating a calculation or script will, to some extent, determine what you must include in your calculation or script.
For example, the amount and type of information available on a form may be different depending on the event timing you choose; therefore,
a calculation or script that retrieves a value from a field may have different results if run before instead of after a form filler performs certain
actions. For more information about events, see “Events” on page 24.
Depending on the type of form you are creating, some events may never occur. For example, if you are creating a form that has a fixed layout
and no interactive objects, then interactive events associated with form filler actions may never occur and, as a result, any scripts associated
with those events will not run.
Although Designer ES2 includes support for a wide variety of form events, it is possible to accomplish a wide variety of common calculation
and scripting tasks by using only a few events that occur at major changes in a form’s state, such as the following events:
• docReady Initiates immediately after the form opens in Acrobat or Adobe Reader® and immediately before the form filler can begin
interacting with form objects. This event is the last event to occur before control of the form is given to the form filler.
• enter Initiates when the form filler changes the focus to a particular field, button, or subform.

• exit Initiates when the form filler changes the focus from a particular field, button, or subform, to another object.

• change Initiates when a form filler makes a change to a field value. This event is most commonly used with drop-down lists or list
boxes to execute a script when a form filler makes a change to the current value.
• click Initiates when a form filler clicks a field or button. This event is most commonly used with buttons to execute a script when a
form filler clicks the button.

To view scripting events and scripts

The Script Editor, provides several ways to view scripting events for objects in your form, depending on the type of object or objects you
select, and the quantity of events you want to display.
Before you begin, you must perform the following actions:
• If the Script Editor is not displayed on the screen, select Window > Script Editor.
• If the Script Editor is not large enough to display more than one line of script at a time, drag its lower line down to increase its size.

To view a scripting event for a single object in the Script Editor

1 Select an object in your form.
2 In the Show list, select a valid scripting event.

To view a scripting event for a container object and its children in the Script Editor
1 If it is not already in multiline mode, expand the Script Editor to display multiple lines of script and ensure that the Show Events for
Child Objects option is selected.
2 Select a container object, such as a subform.
3 In the Show list, select a valid scripting event.
 LIVECYCLE DESIGNER ES2 21
Creating Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

The events appear in the script editing field of the Script Editor, separated by the reference syntax for each event. Note that certain events
only apply to specific types of objects. When you select a script event, the script editing field of the Script Editor only displays valid
instances of the event. For example, if you select a subform that contains a drop-down list and select the preOpen event, the Script editor
displays a single entry representing the drop-down list. This is because the preOpen event only applies to drop-down lists. Alternatively,
selecting the enter event displays two entries, one for the drop-down list and one for the subform.
Note: The Show list denotes events that contain scripts using a trailing asterisk (*) after the name of the event. If an event contains a script,
when you select the event from the Show list, the source appears in the script editing field of the Script Editor.

To view all scripting events for a single object in the Script Editor
1 Select an object in your form.
2 In the Show list, select All Events.
The events appear in the script editing field of the Script Editor, separated by the reference syntax for each event.

To view all scripting events for a container object and its children in the Script Editor
1 If it is not already in multiline mode, expand the Script Editor to display multiple lines of script and ensure the Show Events for Child
Objects option is selected.
2 Select a container object, such as a subform.
3 In the Show list, select All Events.
The events appear in the script editing field of the Script Editor, separated by the reference syntax for each event.

To view all scripts for a single object in the Script Editor

1 Select an object that has scripts attached.
2 In the Show list, select Events With Scripts.
The scripts appear in the script editing field of the Script Editor, separated by the reference syntax for each event.

To view all scripts for a container object and its children in the Script Editor
1 If it is not already in multiline mode, expand the Script Editor to display multiple lines of script and ensure that the Show Events for
Child Objects option is selected.
2 Select a container object, such as a subform. All events for the container object and any child objects appear in the Script Editor.
3 In the Show list, select All Events.
The scripts appear in the script editing field of the Script Editor, separated by the reference syntax for each event.

Determining where to run your calculation or script

For each calculation and script created in Designer ES2, you must specify the location where you want the calculation or script to run.
Unless you are using server-based processing such as Forms ES2, you should ensure that all of your calculations and scripts are set to run
on the client application (for example, on Acrobat or a web browser).
Note: FormCalc calculations and scripts do not work on forms rendered as HTML and are ignored during form filling.
If you are using server-based processing, you can choose between running calculations on the client application, or running them on the
server. By choosing to have calculations and scripts run on the server, you are choosing to run the scripts at a specific point during the form-
rendering process.
If you choose Client And Server from the Run At list, your calculation or script is available to both client and server-based applications. This
option is useful, for example, if you do not know whether your users will have client or server applications when they attempt to use your
form. It is also useful if you want certain form objects to behave one way to a client application and another to a server-based application.
 LIVECYCLE DESIGNER ES2 22
Creating Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Testing and debugging calculations and scripts

After you create your calculations or scripts and tested your form design, you may discover scripting errors or unexpected field values as a
result of scripting syntax errors.
Designer ES2 includes three primary methods for testing and debugging your calculations and scripts:
• Using the Designer ES2 workspace palettes. For more information, see “Using the workspace to debug calculations and scripts” on
page 14.
• For JavaScript only, using the JavaScript Debugger to assist you in testing your scripts. For more information about using the debugger,
see “JavaScript Debugger in Acrobat Professional” on page 71.
• Using the host model and event model properties and methods to troubleshoot your form.
The host model and event model provide functionality that lets you interact with either the host application or the various form events.
These models are useful for returning information that can assist you in debugging calculation and scripts.
For example, the following script returns a message at run time indicating the name of the event on which the script is placed. This indicates
that a particular event has fired:
xfa.host.messageBox(xfa.event.name) // FormCalc
xfa.host.messageBox(xfa.event.name); // JavaScript

Another example of using the host model and event model methods is to obtain the value of a field on an interactive form before a user
manually changed it. This is useful for observing how the objects on your form design respond to user-entered data:
xfa.host.messageBox(xfa.event.prevText) // FormCalc
xfa.host.messageBox(xfa.event.prevText); // JavaScript

To check script syntax

While you work on a form design, you can check all JavaScript or FormCalc scripts for syntax errors to ensure that the form functions as
expected before you distribute it for use. Any script syntax errors found in the form are displayed in the Report palette on the Warnings tab.
On the Warnings tab in the Report palette, each error is listed on a separate numbered line, along with the event or script object name and
a description of the error. If multiple events are displayed, the line numbering for each event begins at 1.
You can click any script error in the list to display the relevant script, highlight the line that contains the error, and locate the insertion point
at the beginning of the highlighted line. Scripting syntax errors are also reported in the Warnings tab when you save a form design or preview
it using the Preview PDF tab.
Note: You can also use the Go To Line dialog box to select the event you want to see. The script event drop-down list includes the System Object
Model (SOM) expression, as shown in the header lines, for each event currently visible in the Script Editor.
❖ In the Script Editor, select Tools > Check Script Syntax.

Working around security restrictions

Script that modifies the sourceSet model or its children makes the form's certification invalid and the form can no longer be trusted. Because
a form can become certified at any time during its life cycle, it is important to use scripting techniques that prevent the form from failing
after it is certified.
You must work with clones of the model rather than with the model if you intend to use scripts that modify the sourceSet model or any of
its children. Cloning prevents the form from failing when scripts modify a data model. For example, forms that execute common tasks, such
as displaying records in a database or selecting specific records in a database, require the modification of data connection nodes contained
within the sourceSet model.
To clone the sourceSet model, you must create a method on the script that defines the data connection that you want to modify within the
sourceSet model and make sure that the script keeps using the clone instead of the definition.
Consider the following script from a data drop-down list. The script populates the list from data from a from a data source.
 LIVECYCLE DESIGNER ES2 23
Creating Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

...
var oDB = xfa.sourceSet.nodes.item(nIndex);
...
// Search node with the class name "command"
var nDBIndex = 0;
while(oDB.nodes.item(nDBIndex).className != "command")
nDBIndex++;

oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayBOF", "bofAction");
oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayEOF", "eofAction");

To clone the sourceSet model, you need to change the line that accesses it by appending the clone (1) method to the end of the statement:
var oDB = xfa.sourceSet.nodes.item(nIndex).clone(1);

Note: You can store the cloned data connection node in a variable or a variable defined in a script object.
 24

4. Events
Every calculation or script you attach to a form object is associated with a specific event. An event is defined as a particular occurrence or
action that can change the state of a form and, when the change of state occurs, automatically invoke a calculation or script associated with
the event. Events occur at various times, from the beginning of the form rendering process when merging data with a form design, all the
way through to a form filler interacting with objects on a form in a client application. By applying calculations and scripts to specific events,
you can control every aspect of how you present form objects, as well as form data, and how the objects and data respond to form filler inter-
action.
A single change of state or form filler action may trigger multiple events. For example, tabbing from the current field to the next field triggers
both the exit event for the current field and the enter event for the next field. If the current and next fields are in different subforms, a
total of four events are triggered; namely, exit events for the current field and subform, and enter events for the next field and subform.
In general, each of the different categories of form events follow a predictable ordering.

Types of events
Form events fall into one of the following categories:
Process events This type of event initiates automatically as the result of an internal process or action related to objects on a form. For
example, if a form filler clicks a button that adds a new page to the form, the initialize, calculate, validate, and layout:ready
process events initiate automatically for the new page.
Interactive events This type of event initiates as a direct result of form filler actions. For example, if a form filler moves the pointer over a
field on a form, the mouseEnter event initiates in response to the action.
Application events This type of event initiates as a result of the actions that either a client application or a server application performs. For
example, you can create a calculation or script to perform a task immediately after the form is saved by using the postPrint event.

Process events
Process events initiate automatically as the result of an internal process or action related to a form or objects on a form. These events initiate
immediately following significant form changes; for example, after a form design is merged with data or after the form pagination process
finishes. Process events also initiate immediately after interactive events initiate. For example, immediately after any interactive event
initiates, the calculate event initiates followed by the validate event.
The following list contains the process events, which are available from the Show list in the Script Editor:
• calculate
• form:ready
• indexChange
• initialize
• layout:ready
• validate
Process events can initiate many times as a result of dependencies; that is, actions associated with a single event that ultimately initiates one
or more additional events. Using an example of a form filler clicking a button to reveal a previously hidden portion of the form, after the
form filler clicks the button, not only does a series of interactive and processing events initiate for the button itself, but a number of process
events for the new subform initiates as well.
 LIVECYCLE DESIGNER ES2 25
Events LiveCycle Designer ES2 Scripting Basics

The following image represents the general flow of events leading up to a PDF form opening in Acrobat or Adobe Reader.

After the form opens in Acrobat or Adobe Reader, these process events may still initiate as the result of changes made to the form. For
example, the calculate, validate, and layout:ready events for an object initiate immediately after some interactive events occur;
therefore, calculations and scripts attached to the processing events will run multiple times.

Interactive events
Interactive events initiate as a direct result of form filler actions, which makes these events useful for a variety of calculation and scripting
tasks. For example, you can add a script to the mouseEnter event for a text field that changes the border color of the field to blue and a script
to the mouseExit event that changes the border color back to the original color. This action creates a highlighting effect when form fillers
move the pointer over the field to visually assist them while filling the form. Interactive events are also useful for changing form data in
response to a form filler selection. For example, you can add a script to the change event for a drop-down list that updates the data values
in multiple fields in response to the value the form filler selects in the drop-down list.
The following list contains the interactive events, which are available from the Show list in the Script Editor:
• change
• click
• enter
• exit
• mouseDown
• mouseEnter
• mouseExit
• mouseUp
• postOpen
• postSign
• preOpen
• preSign
The following image displays the general flow of events for form fillers who use the mouse to select an object and change its value.
 LIVECYCLE DESIGNER ES2 26
Events LiveCycle Designer ES2 Scripting Basics

Note: This image provides a general flow of events; however, certain form filler actions and form objects can cause alternate event ordering. For
example, if a form filler selects a value from a drop-down list, the mouseExit event occurs after the click event but before the change or full
events. Similarly, if a form filler selects a field, holds down the mouse button, and then exits the field while still holding down the mouse button,
the mouseUp event occurs out of the order described in this image.
 LIVECYCLE DESIGNER ES2 27
Events LiveCycle Designer ES2 Scripting Basics

The following image displays the general flow of events for form fillers who use the keyboard to select an object and change its value.

Application events
Application events initiate as a result of the actions that a client application or a server application perform, either due to a form filler action
or an automated process. Application events do not exist as part of a general flow of events. They are single events that correspond to actions
that the client or server application performs.
The following list contains the processing events, which are available from the Show list in the Script Editor:
• docClose
• docReady
• postPrint
• postSave
• postSubmit
• prePrint
• preSave
• preSubmit
 LIVECYCLE DESIGNER ES2 28
Events LiveCycle Designer ES2 Scripting Basics

For example, the following image displays the general flow of events for the preSave event.

If a form filler saves the form in Acrobat or Adobe Reader, the preSave event initiates immediately before the save operation, followed by
the calculate, validate, and layout:ready events, in that sequence for all objects on the form. The same event sequence initiates if the
form contains a script that programmatically saves the form.
A similar sequence of events occurs for each of the other application events previously listed.

calculate event

Description
Initiates in the following situations:
• When your form design and data merge into your finished form.
• When a change occurs to any value that the calculation is dependent on, such as the value of a particular field, unless the form filler has
manually overridden the calculated value. As a result, the object will display the return value of the event. The properties for manually
overridden fields are located in the Value tab of the Object palette.
• When a field loses focus; for example, when a form filler clicks or uses the Tab key to exit a field.
When using the calculate event to perform calculations or scripts, consider the following potential issues:
• Calculations and scripts on the calculate event must not make any changes to the structure of the form, except for the form field and
data values.
• Content inserted by the calculate event must conform to the associated validations for the object; otherwise, validation errors will
occur.
• Calculations and scripts must not include an infinite loop because it causes the form to update the value continuously. For example, a
script that increments the value of a field as part of a looping expression, such as a while or for loop, could create an infinite loop.
• The last expression evaluated in the calculate event is used to populate the value of the current form object. For example, if the script
on the calculate event first sets the value of the current field to 500 and then sets the value of another field to 1000, both fields will
display the value 1000 at run time. As a result, you need to limit the scripting that you add to the calculate event to those that deal
specifically with setting the value of the current field.
 LIVECYCLE DESIGNER ES2 29
Events LiveCycle Designer ES2 Scripting Basics

Type
Processing event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
Use the calculate event for updating numeric values in fields because this event initiates immediately after most other events. For example,
on a purchase order form, you can use the calculate event for a field to determine the percentage of sales tax due based on the cost of the
order. The calculation will initiate every time a change is made to the values in the form fields, ensuring that the value displayed for the sales
tax is always correct.
However, because the calculate event can initiate many times, you must ensure that the calculation or script you add to the event will not
cause data values to increment unnecessarily. For example, if your sales tax calculation adds the value of the sales tax to the total cost each
time the calculate event initiates, the resulting total cost value on your form may be too large.
For a detailed example of using the calculate event, see “Calculating the field sums” on page 101.

change event

Description
Initiates when a form filler changes the content of a field by performing one of these actions:
• Types a keystroke providing the field has keyboard focus
• Pastes data into the field
• Makes a selection from a list box or drop-down list
• Selects or deselects a check box
• Changes the setting of a group of radio buttons
This event does not initiate in response to changes in the object values as a result of calculations or scripts, or by the merging of the form
design with data.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

(Only for drop-down lists)

Version
XFA 2.1
 LIVECYCLE DESIGNER ES2 30
Events LiveCycle Designer ES2 Scripting Basics

Example
Use this event for any calculations or scripts that must initiate in response to a form filler changing the value of a field. For example, you can
use the change event for a drop-down list to highlight specific rows in a table. Using this technique, each time the form filler selects a value
in the drop-down list, the corresponding row of the table appears highlighted.
Note: Scripting against an object's 'this.rawValue' does not work. Use the event model property $event.fullText instead to get the
object's current value.
For a detailed example of using the change event, see “Getting the current or previous value of a drop-down list” on page 99.

click event

Description
Initiates when a mouse click occurs within the region. When a click event initiates for a text or numeric field, calculations or scripts execute
immediately. However, the value of the field does not change in response to calculations and scripts until the field loses focus.
Note: You cannot place a calculation or script on the click event of a submit button because the calculation or script will override the
submission action. Instead, place any calculations and scripts on the preSubmit event for a submit button.
For more information about form submission actions, see the Designer ES2 Help.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
Use this event for performing an action as a direct response to a form filler clicking a button or selecting a radio button or check box on a
form. For example, you can use the click event for a check box to hide and show a field on the form.
For a detailed example of using the click event, see “Changing the visual properties of an object on the client” on page 96.

docClose event

Description
Initiates at the very end of processing a form, only if all form validations complete with no errors.

Type
Application event
 LIVECYCLE DESIGNER ES2 31
Events LiveCycle Designer ES2 Scripting Basics

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
This event initiates too late to modify a saved form and is intended to provide the ability to generate an exit status or completion message.
For example, you can use the docClose event to display a message to a form filler indicating that the form is completed.

docReady event

Description
Initiates immediately after the form opens in Acrobat or Adobe Reader.

Type
Application event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
This event is the first one that initiates after the form opens in Acrobat or Adobe Reader. Any calculation or scripting tasks that require the
full form, or that should only run once when the form filler first opens the form, should use this event. For example, you can use the
docReady event to check the version of Acrobat or Adobe Reader and return a message to the form filler if the form filler must upgrade the
application before filling the form.

enter event

Description
Initiates when a field or subform gains keyboard focus, whether caused by a form filler action (tabbing into a field or clicking in it) or by a
script programmatically setting the focus.

Type
Interactive event
 LIVECYCLE DESIGNER ES2 32
Events LiveCycle Designer ES2 Scripting Basics

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to provide help text or other messages to a form filler while entering the current field or subform. For example, if a
field requires a value in a specific format, or if filling a field requires special instructions, you can use this event to provide a message to the
form filler indicating the special needs.
For a detailed example of using the enter event, see “Highlighting fields in response to form filler interaction” on page 102.

exit event

Description
Initiates when the field or subform loses keyboard focus, whether caused by a form filler action (tabbing to another field or clicking outside
it) or by a script programmatically removing the focus.
Note: If the purpose of your script is to manipulate the value of the current field, you need to consider attaching your script to the calculate
event.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to provide verification of field data as a form filler moves the focus away from a field. For example, if a field requires
a value, you can use this event to provide a message to the form filler indicating that the field requires some data before the form can be
submitted.
For a detailed example of using the exit event, see “Highlighting fields in response to form filler interaction” on page 102.

form:ready event

Description
Initiates after the form design and data are merged, the finished form exists in memory, and the initialize, calculate, and validate
events are complete.
 LIVECYCLE DESIGNER ES2 33
Events LiveCycle Designer ES2 Scripting Basics

Note: The form:ready event only applies to Design View objects, and does not apply to Master Page objects (see “Process events” on page 24).

Type
Processing event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
You can use this event to perform tasks after the form design and data are merged but before the layout is established. For example, you can
use this event to customize the ordering or placement of subforms on your form before the form is paginated and rendered.

full event

Description
Initiates when the form filler attempts to enter more than the maximum allowed amount of content into a field. For example, if the Limit
Length property for a field is set to 5, and a form filler attempts to enter the string abcdef, the full event initiates when the form filler types
the letter f.
Note: The Limit Length property for a field is located in the Field tab in the Object palette.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
Use this event to indicate to a form filler that a field has reached its maximum capacity. For example, you can output a message to the form
filler indicating that the field is full and provide any steps that should be taken to correct the issue.

indexChange event

Description
Initiates as a result of a subform being inserted, moved, or removed from the form by merging new data with the form or by using scripting.
Keep in mind that the indexChange event does not fire when deleting the last row of a table.
 LIVECYCLE DESIGNER ES2 34
Events LiveCycle Designer ES2 Scripting Basics

Note: This event is received only by the subform instances that are controlled by the instance manager; the event is ignored for subform sets.

Type
Processing event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.5

Example
You can use this event to set properties based on the instance value of a particular object. For example, you can use this event to coordinate
the shading of alternate rows in a table.

initialize event

Description
Initiates for all objects after the form design is merged with data.

Type
Processing event

Support
Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to perform actions when an object is first created, either as the result of a form filler action or during the form creation
process. For example, you can use this event to control settings for new instances of a subform object that a form filler adds to the form by
using a button.

layout:ready event

Description
Initiates after the form design and data are merged, the form exists, and the form’s layout is applied. At this time, the finished form has not
been rendered; therefore, a calculation or script set to run on this event could modify the layout before the form is rendered. This event also
occurs after the form is rendered if a calculation or script changes the data or causes a change to the form in Acrobat or Adobe Reader.
 LIVECYCLE DESIGNER ES2 35
Events LiveCycle Designer ES2 Scripting Basics

Note: Scripts that fire on layout:ready should not do anything that would cause the layout of the form to change. For example, this would include
anything involving subforms or tables that grow or shrink, adding fragments dynamically at run time, adding or removing subform instances,
and toggling the presence setting of an object between hidden and visible.
Note: Fields in interactive forms that contain the layout:ready event are supported in Acrobat 7.0.5 and later.

Type
Processing event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
You can use this event to perform tasks immediately after the form layout is established. For example, you can use this event to determine
the number of pages the form contains.

mouseDown event

Description
Initiates when a form filler presses the mouse button at the same time that the pointer is within a field.
Note: When a mouseDown event initiates for a text or numeric field, calculations or scripts run immediately. However, the value of the field does
not change in response to calculations and scripts until the field loses focus. When a mouseDown event initiates for a signature field, the event
initiates before the signature process begins.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to perform an action as a direct response to a form filler clicking a button, or selecting a radio button or check box
on a form. For example, you can use the mouseDown event for a check box to hide and show a field on the form. This event is conceptually
similar to the click event and has a similar purpose.
 LIVECYCLE DESIGNER ES2 36
Events LiveCycle Designer ES2 Scripting Basics

mouseEnter event

Description
Initiates when the form filler moves the pointer into the area of the field, without necessarily pressing the mouse button. This event is not
initiated when the pointer moves into the field for a different reason; for example, because an overlapping window closes.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
You can use this event to provide visual feedback to a form filler in conjunction with the mouseExit event. For example, you can use this
event to change the border or background color of an object to help visually indicate to form fillers that they are working in a specific field.
For a detailed example of using the mouseEnter event, see “Highlighting fields in response to form filler interaction” on page 102.

mouseExit event

Description
Initiates when a form filler moves the pointer out of the field, even if the form filler is pressing the mouse button. It is not initiated when the
pointer moves out of the field for a different reason; for example, because an overlapping window opens.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
You can use this event to provide visual feedback to a form filler in conjunction with the mouseEnter event. For example, you can use this
event to return the border or background color of an object to its original value to help visually indicate to form fillers that they are no longer
working in a specific field.
For a detailed example of using the mouseExit event, see “Highlighting fields in response to form filler interaction” on page 102.
 LIVECYCLE DESIGNER ES2 37
Events LiveCycle Designer ES2 Scripting Basics

mouseUp event

Description
Initiates when a form filler releases the mouse button at the same time that the pointer is within a field.
Note: When a mouseUp event occurs for a text or numeric field, calculations or scripts run immediately. However, the value of the field does not
change in response to calculations and scripts until the field loses focus.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to perform actions as a direct response to a form filler clicking a button, or selecting a radio button or check box on
a form. For example, you can use the mouseUp event for a check box to hide and show a field on the form. This event is conceptually similar
to the click event and has a similar purpose.

postOpen event

Description
Initiates immediately after a form filler performs an action that causes the data in a drop-down list to appear, such as clicking the arrow icon
on the drop-down list or tabbing into the drop-down list and then using the down arrow. This event initiates after the contents of the drop-
down list are displayed.
Note: This event applies only to the Drop-down List object.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.8
 LIVECYCLE DESIGNER ES2 38
Events LiveCycle Designer ES2 Scripting Basics

Example
You can use this event to handle errors or unexpected outcomes as a result of processing the opening of the drop-down list. For example, if
the preOpen event is dispatched via scripting instead of user interaction, or if the opening of the drop-down list data does not occur as a
result of an error, the postOpen event is still dispatched to let error handling scripts execute.

postPrint event

Description
Initiates immediately after the rendered form is sent to the printer, spooler, or output destination.

Type
Application event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
You can use this event to display information messages to the form filler after the form is printed. For example, you can create a script on
the postPrint event to remind form fillers what steps they need to take to submit the form by hand.

postSave event

Description
Initiates immediately after a form filler saves a form in PDF or XDP format. This event does not initiate when you export a subset of the
form (for example, only form data) to XDP.

Type
Application event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.1

Example
You can use this event to display information messages to the form filler after the form data is saved. For example, you can create a script on
the postSave event to remind form fillers how much time remains for them to successfully complete and submit the form.
 LIVECYCLE DESIGNER ES2 39
Events LiveCycle Designer ES2 Scripting Basics

postSign event

Description
Initiates immediately after a form filler performs an action that applies a digital signature to a form.
Note: This event applies only to the Signature Field object.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.8

Example
You can use this event to inform a user about any restrictions that are imposed now that the form is digitally signed.

postSubmit event

Description
Initiates immediately after a form submits data to the host through the HTTP protocol.
Note: This event does not distinguish between submissions that are initiated by instances of clicking buttons, or submissions made to different
URLs. Any script that needs to make these distinctions must include a script to determine which button was clicked. In general, the postSubmit
event is conceptually similar to the postSave event and serves a similar purpose.

Type
Application event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

(Only for submit buttons)

Version
XFA 2.8

Example
You can use this event to perform actions immediately after the form data is submitted. For example, you can create a script on the
postSubmit event to display confirmation that the submission performed successfully.
 LIVECYCLE DESIGNER ES2 40
Events LiveCycle Designer ES2 Scripting Basics

preOpen event

Description
Initiates when a form filler performs an action that causes the drop-down list to appear, such as clicking the arrow icon on the drop-down
list or by tabbing into the drop-down list and using the down arrow. This event initiates before the contents of the drop-down list are
displayed.
Note: This event applies only to the Drop-down List object.

Type
Interactive event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.4

Example
You can use this event to control the loading of large numbers of list items. For example, you can use this event to load a fixed number of
records from a data source into a drop-down list. This improves the performance of the form for the form filler at run time.

prePrint event

Description
Initiates immediately before the process of rendering a form for printing begins. You cannot cancel printing using this event.
Caution: Avoid using this event to hide or show form objects. For example, if a form filler has already digitally signed the form, using this event
to hide all button objects prior to printing will impact the state of the signature.

Type
Application event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to change the presence of an object to prevent it from printing. For example, you can use this event to hide text or
instructions intended for the form filler to use while filling the form online.
 LIVECYCLE DESIGNER ES2 41
Events LiveCycle Designer ES2 Scripting Basics

preSave event

Description
Initiates immediately before form data is saved in PDF or XDP format. This event does not initiate when the form data or another subset of
the form is exported to XDP.

Type
Application event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to change form data immediately before the data is saved. For example, you can create a script on the preSave event
to scan the data and display a reminder message to the form filler if certain required fields remain empty.

preSign event

Description
Initiates immediately before a form filler performs an action that applies a digital signature to a form.
Note: This event applies only to the Signature Field object.

Type
Interactive event

Support
Client application Availability

Acrobat and Adobe Reader yes

HTML browser no

Version
XFA 2.8

Example
You can use this event to validate the data that the digital signature covers or to provide any information to a user before they apply the digital
signature.
 LIVECYCLE DESIGNER ES2 42
Events LiveCycle Designer ES2 Scripting Basics

preSubmit event

Description
Initiates when a form submits data to the host through the HTTP protocol. At this point, the data is organized into a data set but has not
been sent to the host. Calculations and scripts associated with this event can examine and alter the data prior to the form submission. If the
calculation or script is set to run on the server, the form sends the data to the server indicating that it should run the calculation or script
before performing any additional processing.
Note: This event does not distinguish between submissions initiated by instances of clicking buttons or to different URLs. Any script that needs
to make these distinctions must include code to determine which button was clicked. In general, the preSubmit event is conceptually similar to
the preSave event and serves a similar purpose.

Type
Application event

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

(Only for submit buttons)

Version
XFA 2.1

Example
You can use this event to change form data immediately before the data is submitted. For example, you can create a script on the preSubmit
event to scan the amount of data and display a message to the form filler estimating how long the data submission may take.

validate event

Description
Initiates when the form design and data merge to create your form and when a field loses focus; for example, when a form filler clicks or
uses the Tab key to exit a field. This event initiates again each time the value of a field changes. Calculations and scripts placed on the
validate event provide a method to perform validations that are more specific than those available through the Value tab of the Object
palette.
Calculations and scripts on the validate event are required to return true or false (expressed in a format appropriate to the scripting
language) corresponding to a validation that succeeds or fails, and must not affect the overall form structure of form values. In addition,
calculations and scripts should not attempt to provide feedback to a form filler because that form filler may not be using the form in a client
application such as Acrobat.
Note: Because validations are performed against the content of the form, they cannot be used to verify presentation formatting caused by field
patterns.

Type
Processing event
 LIVECYCLE DESIGNER ES2 43
Events LiveCycle Designer ES2 Scripting Basics

Support

Client application Availability

Acrobat and Adobe Reader yes

HTML browser yes

Version
XFA 2.1

Example
You can use this event to verify object values, particularly in situations where object data must conform to specific rules. For example, you
can create a script on the validate event to verify that a total cost field on a purchase order form does not have a negative value.
For a detailed example of using the validate event, see “Setting a field as required at run time” on page 101.
 44

5. Scripting with FormCalc and JavaScript

Although FormCalc and JavaScript are intended for two different types of users, there is some overlap between the types of built-in functions
they offer. The following table lists all available FormCalc functions and whether a comparable function exists within JavaScript.
For more information about FormCalc functions and their parameters, see “Built-in function syntax” on page 48.

FormCalc function Description JavaScript method equivalent

Abs(n1) Returns the absolute value of a numeric value or expres- Math.abs(n1)

sion.

Apr(n1, n2, n3) Returns the annual percentage rate for a loan. None

At(s1, s2) Locates the starting character position of a string within String.search(s1)
another string.

Avg(n1 [, n2... ] ) Evaluates a set of number values and/or expressions and None
returns the average of the non-null elements contained
within that set.

Ceil(n1) Returns the whole number greater than or equal to a Math.ceil(n1)

given number.

Choose(n1, s1 [, s2... ] ) Selects a value from a given set of parameters. None

Concat(s1 [, s2... ] ) Returns the concatenation of two or more strings. String.concat(s1, s2 [, s3 ... ])

Count(n1 [, n2...]) Evaluates a set of values and/or expressions and returns None
the number of non-null elements contained within the
set.

CTerm(n1, n2, n3) Returns the number of periods needed for an invest- None
ment earning a fixed, but compounded, interest rate to
grow to a future value.

Date() Returns the current system date as the number of days Date.getDate()
since the epoch.
The JavaScript Date object does not use the
epoch as a reference point.

Date2Num(d1 [, f1 [, k1 ] ] ) Returns the number of days since the epoch, given a The JavaScript Date object does not use the
date string. epoch as a reference point.

DateFmt([ n1 [, k1 ] ] ) Returns a date format string, given a date format style. None

Decode(s1 [, s2 ] ) Returns the decoded version of a given string. Partial support

JavaScript only supports URL encoded values

that contain no escape characters.

Encode(s1 [, s2 ] ) Returns the encoded version of a given string. Partial support

JavaScript only supports URL encoded values

that contain no escape characters.

Eval() Returns the value of a given form calculation. eval(s1)

Exists(v1) Determines whether the given parameter is a valid refer- None

ence syntax to an existing object.

Floor(n1) Returns the largest whole number that is less than or Math.floor(n1)
equal to the given value.
 LIVECYCLE DESIGNER ES2 45
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

FormCalc function Description JavaScript method equivalent

Format(s1, s2) Formats the given data according to the specified None
picture format string.

FV(n1, n2, n3) Returns the future value of consistent payment amounts None
made at regular intervals at a constant interest rate.

Get(s1) Downloads the contents of the given URL. None

HasValue(v1) Determines whether the given parameter is a valid refer- None

ence syntax with a non-null, non-empty, or non-blank
value.

IPmt(n1, n2, n3, n4, n5) Returns the amount of interest paid on a loan over a set None
time.

IsoDate2Num(d1) Returns the number of days since the epoch, given a None
valid date string.

IsoTime2Num(d1) Returns the number of milliseconds since the epoch, None

given a valid time string.

Left(s1, n1) Extracts a specified number of characters from a string, String.substring(n1, n2)
starting with the first character on the left.

Len(s1) Returns the number of characters in a given string. String.length

LocalDateFmt( [ n1 [, k1 ] ] ) Returns a localized date format string, given a date None

format style.

LocalTimeFmt( [ n1 [, k1 ] ] ) Returns a localized time format string, given a time None

format style.

Lower(s1 [, k1 ] ) Converts all uppercase characters within a specified String.toLowerCase(s1)

string to lowercase characters.

Ltrim(s1) Returns a string with all leading white space characters None
removed.
You can use JavaScript regular expressions to
perform this operation.

Max(n1 [, n2... ] ) Returns the maximum value of the non-null elements in Math.max(n1, n2)
the given set of numbers.

Min(n1 [, n2... ] ) Returns the minimum value of the non-null elements of Math.min(n1, n2)
the given set of numbers.

Mod(n1, n2) Returns the modulus of one number divided by another. Use the modulo (%) operator.

NPV(n1, n2 [, ... ] ) Returns the net present value of an investment based on None
a discount rate and a series of periodic future cash flows.

Num2Date(n1[, f1 [, k1 ] ] ) Returns a date string given a number of days since the None
epoch.

Num2GMTime(n1 [,f1 [, k1 ] ] ) Returns a GMT time string given a number of millisec- None
onds from the epoch.

Num2Time(n1 [,f1 [, k1 ] ] ) Returns a time string given a number of milliseconds None

from the epoch.

Oneof(s1, s2 [, s3... ] ) Returns true (1) if a value is in a given set and false (0) if it None
is not.
This function is similar to the
String.search(s1) method and
String.match(expression) method.
 LIVECYCLE DESIGNER ES2 46
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

FormCalc function Description JavaScript method equivalent

Parse(s1, s2) Analyzes the given data according to the given picture None
format.

Pmt(n1, n2, n3) Returns the payment for a loan based on constant None
payments and a constant interest rate.

Post(s1, s2 [, s3 [, s4 [, s5 ] ] ] ) Posts the given data to the specified URL. None

PPmt(n1, n2, n3, n4, n5) Returns the amount of principal paid on a loan over a None
period of time.

Put(s1, s2 [, s3 ] ) Uploads the given data to the specified URL. None

PV(n1, n2, n3) Returns the present value of an investment of periodic None
constant payments at a constant interest rate.

Rate(n1, n2, n3) Returns the compound interest rate per period required None
for an investment to grow from present to future value in
a given period.

Ref() Returns a reference to an existing object. None

Replace(s1, s2 [, s3 ] ) Replaces all occurrences of one string with another String.replace(s1, s2)
within a specified string.

Right(s1, n1) Extracts several characters from a given string, begin- String.substring(n1, n2)
ning with the last character on the right.

Round(n1 [, n2 ] ) Evaluates a given numeric value or expression and Math.round(n1)

returns a number rounded to the given number of
decimal places.

Rtrim(s1) Returns a string with all trailing white space characters None
removed.
You can use JavaScript regular expressions to
perform this operation.

Space(n1) Returns a string consisting of a given number of blank None

spaces.

Str(n1 [, n2 [, n3 ] ] ) Converts a number to a character string. FormCalc String(n1)

formats the result to the specified width and rounds to
or
the specified number of decimal places.
Number.toString(radix)

Stuff(s1, n1, n2 [, s2 ] ) Inserts a string into another string. None

Substr(s1, n1, n2) Extracts a portion of a given string. String.substring(n1, n2)

Sum(n1 [, n2... ] ) Returns the sum of the non-null elements of a given set None
of numbers.

Term(n1, n2, n3) Returns the number of periods required to reach a given None
future value from periodic constant payments into an
interest-bearing account.

Time() Returns the current system time as the number of milli- Date.getTime()
seconds since the epoch.
The JavaScript Date object does not use the
epoch as a reference point.

Time2Num(d1 [, f1 [, k1 ] ] ) Returns the number of milliseconds since the epoch, None

given a time string.

TimeFmt([n1 [, k1 ] ] ) Returns a time format, given a time format style. None

 LIVECYCLE DESIGNER ES2 47
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

FormCalc function Description JavaScript method equivalent

UnitType(s1) Returns the units of a unitspan. A unitspan is a string None

consisting of a number followed by a unit name.

UnitValue(s1 [, s2 ] ) Returns the numeric value of a measurement with its None

associated unitspan after an optional unit conversion.

Upper(s1 [, k1 ] ) Converts all lowercase characters within a string to String.toUpperCase()

uppercase.

Uuid(n1) Returns a Universally Unique Identifier (UUID) string to None

use as an identification method.

Within(s1, s2, s3) Returns true (1) if the test value is within a given range, String.search(s1)
and false (0) if it is not.

WordNum(n1 [, n2 [, k1 ] ] ) Returns the English text equivalent of a given number. None

Using FormCalc
FormCalc is a simple yet powerful calculation language modeled on common spreadsheet software. Its purpose is to facilitate fast and
efficient form design without requiring a knowledge of traditional scripting techniques or languages. Using several of the built-in functions,
inexperienced FormCalc users can quickly create forms that save users from performing time-consuming calculations, validations, and
other verifications. This way, you can create a basic set of rules for the form design that allows the resulting form to react according to the
data it comes into contact with.
Within Designer ES2, FormCalc is the default scripting language in all scripting locations with JavaScript as the alternative. For information
on setting your default scripting language, see “Configuring the Designer ES2 workspace for Scripting” on page 11.
Caution: If you are developing forms for use with a server-based process (for example, using Forms ES2), with the intent of rendering your forms
in HTML, you should develop your calculations and scripts in JavaScript. FormCalc calculations are not valid in HTML browsers, and are
removed prior to the form being rendered in HTML.
FormCalc treats each new line in the Script Editor as a new expression to evaluate.

Using built-in functions

The built-in functions that comprise FormCalc cover a wide range of areas, including mathematics, dates and times, strings, finance, logic,
and the web. These areas represent the types of functionality that usually occur in forms. The purpose of the functions is to provide quick
and easy manipulation of form data in a useful way.
At the most basic level, a calculation can consist of only a single FormCalc function. However, a single FormCalc function can use other
FormCalc functions as parameters.

To attach a FormCalc function to an object

You can add a FormCalc function to any form design object that allows calculations and scripts, excep for the script object.
1 Make sure that you have the multiline version of the Script Editor displayed in the Designer ES2 workspace.
2 Select a field on your form.
3 In the Show list, select the calculate event.
4 Click the Functions icon or F10 to display a list of FormCalc functions.
5 Select the appropriate function and press Enter.
6 Replace the default function syntax notation with your own set of values.
7 Click the Preview PDF tab to test the form.
 LIVECYCLE DESIGNER ES2 48
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

Built-in function syntax

Each FormCalc function uses a specific syntax notation that you must follow in order for the function to execute correctly. This table
describes, generally, the pieces of syntax notation.

Syntax notation Replacement values

d A valid date string (for example, 03/15/1996)

f A valid date format string (for example, MM/DD/YYYY)

k A valid locale identifier (for example, fr_FR)

n A valid numeric value. Notice that the range of valid values varies from function to function.

s A valid unit of measurement (for example, “in” for inches).

v A valid reference syntax.

n1, n2, n3 All values are required.

[ [ n [, k ] ] ] No values are required, but you can choose to specify just n, or both n and k.

n1 [, n2 ... ] n1 is required, but you can choose to specify an unlimited number of additional values.

d [, f [, k ] ] d is required, but you can choose to also specify f or both f and k.

For more information and examples of valid syntax notation values, see the appropriate FormCalc functions in Designer ES2 Help.

Creating basic calculations

About basic calculations

Simple expressions are the most basic instances of scripting. These expressions do not involve using FormCalc built-in functions and are
never more than a single line. Add simple expressions to the calculate event of a particular field or object so that the expression value can
output onto your form.

Examples of basic calculations

These examples are all of simple expressions:
2
"abc"
2 - 3 * 10 / 2 + 7

Each simple expression evaluates to a single value by following a traditional order of operations, even if the order is not always obvious from
the expression syntax. For example, the following sets of expressions produce equivalent results.

Expression Equivalent to Result

"abc" "abc" abc

2 - 3 * 10 / 2 + 7 2 - (3 * 10 / 2) + 7 -6

(10 + 2) * (5 + 4) (10 + 2) * (5 + 4) 108

0 and 1 or 2 > 1 (0 and 1) or (2 >1) 1 (true)

2 < 3 not 1 == 1 (2 < 3) not (1 == 1) 0 (false)

 LIVECYCLE DESIGNER ES2 49
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

As implied in the previous table, all FormCalc operators carry a certain precedence when they appear within expressions. The following
table illustrates this operator hierarchy.

Precedence Operator

Highest =

(Unary) - , + , not

*,/

+,-

< , <= , > , >= , lt , le , gt , ge

== , <> , eq , ne

& , and

Lowest | , or

All the previous examples are valid, simple expressions that you can add to a form field or object that accepts calculations and scripts. For
example, if you create a form in Designer ES2 with a single numeric field, add the following calculation to the calculate event in the Script
Editor.
 LIVECYCLE DESIGNER ES2 50
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

Then, when you click the Preview PDF tab to view the completed form, the value of the simple expression appears in the text field.

If the value does not appear in the preview, ensure that your simple expression appears in the calculate event of the form design object. Also,
ensure that you installed Designer ES2 and Acrobat correctly.

Using JavaScript
To allow form designers more flexibility and scripting power, Designer ES2 supports the use of JavaScript version 1.6 or earlier in all situa-
tions that support scripting.
Form developers who are familiar with JavaScript can apply their existing expertise directly to Designer ES2. Designer ES2 provides several
properties and methods that enhance JavaScript so that you to access field and object values. These properties and methods combined with
the Designer ES2 reference syntax provide you with easy manipulation of form values and data.
Note: The Script Editor does not provide syntax error checking for scripts created using JavaScript. In addition, statement completion options do
not appear for standard JavaScript objects or methods.

Creating scripts using JavaScript

Creating scripts in Designer ES2 using JavaScript is similar to creating JavaScript in other applications. You can take advantage of previous
knowledge of JavaScript concepts, reuse JavaScript functions using the Designer ES2 script object, and take advantage of JavaScript language
functionality.
However, notice that although previous JavaScript knowledge is transferable, to effectively use JavaScript on your form design, you must
understand how to construct Designer ES2 reference syntax. Specifically, you must know how to correctly use the XML Form Object Model
reference syntax to access objects on your form design.
 LIVECYCLE DESIGNER ES2 51
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

This table outlines the key concepts for developing scripts in JavaScript for Designer ES2. The table also provides the location for more infor-
mation on each concept within the Designer ES2 Help.

Key concept For more information see...

Creating references to object properties and values, including using the “Referencing object properties and values” on page 58
resolveNode method.
“To use statement completion to create calculations and scripts” on page 19

Using the host and event models to test and debug your form. “Testing and debugging calculations and scripts” on page 22

“Referencing object properties and values” on page 58

Using a script object to reuse your existing JavaScript functions. “Creating and Reusing JavaScript Functions” on page 66

In addition to the resources available in the Designer ES2 Help, the LiveCycle Developer Center contains extensive scripting resources and
documentation.

Enforcing strict scoping rules in JavaScript

When working with JavaScript in forms, it is important to declare objects and variables within the scope they are intended. Globally
declaring objects or variables unnecessarily can cause performance problems. Strict scoping was introduced in Designer 8.1 to improve the
run time and memory usage of a form.

What is scope in JavaScript?

Scope works outwardly so that everything within curly brackets ({}) can see outside them. However anything outside the curly brackets
cannot access anything inside them.
In the following example, the first curly bracket opens the function scope and the second one closes it. Everything between the curly brackets
is within the scope of foo ().
 LIVECYCLE DESIGNER ES2 52
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

The scope in the following example is valid because var nFooVar = nOutsideVar inside the curly brackets can see var nOutsideVar =
2 outside the curly brackets.

In contrast, the following example shows an invalid scope because var nOutsideVar = nFooVar cannot access var nFooVar =4 within
the curly brackets.

Scope in scripting describes pieces of scripts that can access pieces. The pieces of script can be variables or functions.

What is scope XML?

Scope in a form design is about hierarchy. For example, to access the subform inside in the following XML source, you must type
outside.inside.
<subform name=“outside”>
<subform name=“inside”>
…
</subform>
</subform>
 LIVECYCLE DESIGNER ES2 53
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

You do not type inside.outside because you must access the outermost subform first and drill inwards.

SOM expressions and scope

In forms that are targeted for Acrobat or Adobe Reader 8.1, SOM expressions are properly scoped as shown in this example:
<subform name="a">

<subform name="b"/>

In forms targeted for Acrobat or Adobe Reader 8.0, the SOM expression a.b.a returns the subform a. In forms targeted for Acrobat or
Adobe Reader 8.1, the SOM expression a.b.a returns null because subform b does not have a child named a. In Acrobat or Adobe Reader
9.0 or later, the expression returns an error because a is not a valid child of b.
In Acrobat or Adobe Reader 8.1, functions and variable within a node’s script do not become global (script objects being the exception) as
shown in this example:
<field name="field1">

event activity="initialize">

<script contentType="application/x-javascript">

// Function bar() is scoped to field1.initialize; nothing outside <event activity="initialize">

scope can see inside here (in 8.1)

function bar()

return "bar";

</script>

</event>

/field>

field name="field2">

<event activity="click">

<script contentType="application/x-javascript">

field1.bar();

</script>

</event>

</field>

When you click field 2 in a form targeting Acrobat or Adobe Reader 8.0, the function bar() executes.
When you click field 2 in a form targeting Acrobat or Adobe Reader 8.0, the function bar() does not execute. The reason is because
function bar() is available only from within the initialized script of field1.
 LIVECYCLE DESIGNER ES2 54
Scripting with FormCalc and JavaScript LiveCycle Designer ES2 Scripting Basics

Scoping and script objects

Script objects have global scope; therefore, anyone can access them from anywhere. If you have a method that you want both
field1.initialize and field2.click to access, place it in a script object. Strict scoping means that you cannot call bar() from
anywhere in a form. You also get a run-time error indicating that the function bar() could not be resolved. The script engine looked for
bar() within the scope that you have access to and did not find it.

Scoping and target version

If you use strict scoping, remember that you get performance improvements in forms targeted for Acrobat or Adobe Reader 8.1 and later.
Avoid using strict scoping in forms targeted for older versions of Acrobat or Adobe Reader. Otherwise, the scripts in the forms can work
differently. For existing forms, back up the form before you enable strict scoping and always verify the script afterwards. When you enable
strict scoping and then change the target version to earlier than Acrobat or Adobe Reader 8.1, warning messages appear.

When to use scoping

When a form is targeted for Acrobat or Adobe Reader 8.1 and strict scoping is on, declared JavaScript variables are released after each script
executes. When a form is targeted for Acrobat or Adobe Reader 9.0 and later, strict scoping does not release all the JavaScript variables. The
excepting is when you remerge or import new data.
The performance enhancements with strict scoping rules apply to forms targeted for Acrobat or Adobe Reader 8.1 and later. Do not apply
strict scoping rules to forms that are targeted for versions of Acrobat or Adobe Reader earlier than 8. Otherwise, the scripts can behave
differently or not work.

To enable strict scoping

1 Select File > Form Properties and click the Defaults tab.
2 Select Enforce Strict Scoping Rules In JavaScript and then click OK.

To attach a JavaScript script to an object

You can add a JavaScript script to any form design object that allows calculations and scripts, including the script object.
1 Make sure that you have the multiline version of the Script Editor displayed in the Designer ES2 workspace.
2 Select a field on your form. For example, add a new text field to your form design.
3 In the Show list, select a valid event. For example, using the new text field, select the docReady event.
4 In the Run At list, select where you want the script to execute. For example, for the new text field, select Client.
5 Click the Functions icon or F10 to display a list of JavaScript functions.
6 Select the desired function, and press Enter.
7 Replace the default function syntax notation with your own set of values. Alternatively, you can create your own script manually in the
Script Source field of the Script Editor. For example, in the new text field, add the following JavaScript to the Script Source field:
this.border.fill.color.value = "255,0,0";
8 Click the Preview PDF tab to test the form. The text appears red for the new button object when the form is displayed in the Preview
PDF tab.
 55

6. Variables
You can define form variables in Designer ES2 to store specific information in a central, accessible location. A variable typically acts as a
placeholder for text that you might have to change in the future. Form variables in Designer ES2 are always of the type "string". For example,
a variable can store the text of a message box title. When the text needs to change, all you have to do is open the affected form or template
and update the text once through the variable definition. Designer ES2 automatically propagates the new text across all instances of the
inserted variable.
Keep in mind that form variables are defined outside of the Script Editor, and are accessible by scripts on all objects on a form, as opposed
to scripting variables that you create in a specific FormCalc or JavaScript script.
You can create, view, and delete variables without using scripting. However, you must use scripting to access the values stored by variables
and manipulate them, or to apply the values to objects on your form.
Note: Form variable values reset each time you open a form.
Before you create a variable, decide the name of the variable and the text that it will contain. Variable definitions are saved with the form or
template.

Naming variables
At run time, naming conflicts occur when the names of variables are identical to those used as XML Form Object Model properties,
methods, or form design field names. These conflicts can cause scripts to return unexpected values; therefore, it is important to give each
variable a unique name. Here a couple of examples:
• Use the variable name fieldWidth and fieldHeight instead of x and y.
• Use the form design object name clientName instead of name.
Note: Variable names are case-sensitive and should not contain spaces.

To define a text variable

1 Select File > Form Properties.
2 In the Variables tab, click New (Insert) .
3 In the Variables list, type a unique name for the variable and press Enter. Variable names are case-sensitive and should not contain
spaces.
4 Click once in the box to the right and type the text you want to associate with the variable.
 LIVECYCLE DESIGNER ES2 56
Variables LiveCycle Designer ES2 Scripting Basics

The variable appears in the Hierarchy palette at the form level.

A. New form variable

To view a text variable definition

1 Select File > Form Properties.
2 Click the Variables tab and select the variable from the Variables list. The associated text is displayed in the box to the right.

To delete a text variable

1 Select File > Form Properties.
2 In the Variables tab, select the variable and click Delete (Delete) .

Using variables in calculations and scripts

After you have created form variables, you only need to reference the variable name in your calculations and scripts in order to obtain the
value of the variable.
Caution: When naming variables, you should avoid using names that are identical to the names of any XML Form Object Model properties,
methods, or object names. For information about XML Form Object Model properties, methods, and objects, see the Designer ES2 Scripting
Reference.
For example, create the following form variable definitions.

Variable name Value

firstName Tony

lastName Blue

age 32

In FormCalc, you can access the variable values in the same manner that you access field and object values. In this example, the values are
assigned to three separate fields:
TextField1 = firstName
TextField2 = lastName
NumericField1 = age

You can also use variables in FormCalc functions in the same way, as shown in this example:
Concat( "Dear ", firstName, lastName )
 LIVECYCLE DESIGNER ES2 57
Variables LiveCycle Designer ES2 Scripting Basics

In JavaScript, you reference variable values by using the .value property instead of the .rawValue property that is used for field and object
values, as shown in this example:
TextField1.rawValue = firstName.value;
 58

7. Referencing Objects in Calculations and Scripts

Although both FormCalc calculations and JavaScript scripts have rules for structuring code, both rely on the same reference syntax when
accessing form object properties and values. The XML Form Object Model provides a structured way to access object properties and values
through a compound naming convention with each object, property, and method separated by dot (.) characters.
In general, each reference syntax has a similar structure divided into the following sections:
• The names of the parent objects in the form hierarchy that is used to navigate to a specific field or object. You can use the Hierarchy
palette and Data View palette to determine the location of an object relative to other objects in the form and in any associated data.
• The name of the object you want to reference.
• The the name of the property or method you want to access. This section may also include XML Form Object Model objects that precede
the property or method in the structure but that do not appear as objects in the Hierarchy palette.
For example, the following illustration shows the reference syntax for accessing the value of a text field on a form design that uses the default
object-naming conventions:

A. Form hierarchy objects B. Object name C. Property or method name

Note: By default, the subform object that represents the first page of a new form is unnamed. In the reference syntax above, the unnamed subform
is represented by #subform.
The reference syntax notation structure varies slightly, depending on the specific situation. For example, a fully qualified reference syntax
works in any situation; however, in some cases, you can use a shortened reference syntax or a reference syntax shortcut to reduce the size of
the syntax.

Referencing object properties and values

The reference syntax you use to access or modify object properties and values takes one of the following forms:
Fully qualified Reference syntax includes the full object hierarchy, beginning with the xfa root node. The fully qualified syntax accurately
accesses the property or value of an object regardless of where the calculation or script that contains the reference syntax is located.
Abbreviated The reference syntax is shortened either because of the relative positioning of the calculation or script that contains the
reference syntax and the object syntax references, or because shortcuts are used. In general, although an abbreviated reference syntax is faster
to create, the disadvantage is that it works only as long as the objects remain in the same positions relative to each other.
 LIVECYCLE DESIGNER ES2 59
Referencing Objects in Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

For example, this illustration shows the hierarchy of a sample purchase order form.

This illustration shows a fully qualified reference syntax, for both FormCalc and JavaScript, to access the value of the txtCondition field.
This reference syntax could be used as part of a calculation or script on any object on the form.

A. Root Node B. Model C. Form design root node D. Page object E. Subform name F. Object name G. Property or method name

Note: Even though the reference syntax is common to both FormCalc and JavaScript, you must observe the conventions for each scripting
language. For example, the reference syntax in the example above works as is for FormCalc; however, you would need to include a trailing
semicolon (;) character for JavaScript.
If two objects exist in the same container, such as a subform, they are referred to as sharing the same context. Where objects exist in the same
context, you can use an abbreviated reference syntax that includes only the name of the object followed by the property or method you want
to access. For example, using the example from above, the following abbreviated reference syntax accesses the value of the txtCondition
field from any of the fields in the total subform:
txtCondition.rawValue

If two objects exist in different containers, they do not share the same context. In this case, you can use an abbreviated reference syntax;
however, the syntax must begin with the name of the highest level container object that the two objects do not have in common. For example,
using the hierarchy above, the following abbreviated reference syntax accesses the value of the address field from the txtCondition field:
 LIVECYCLE DESIGNER ES2 60
Referencing Objects in Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

header.address.rawValue

Due to the way the XML Form Object Model is structured, some object properties and methods exist on child objects of the objects on the
form. These child objects exist only as part of the XML Form Object Model and do not appear in the Hierarchy and Data View palettes. To
access these properties and methods, you must include the child objects in the reference syntax. For example, the following reference syntax
sets the tool tip text for the txtCondition field:
txtCondition.assist.toolTip.value = "Conditions of purchase." // FormCalc
txtCondition.assist.toolTip.value = "Conditions of purchase."; // JavaScript

For more information about the XML Form Object model objects and their structure, see Designer ES2 Scripting Reference.

Referencing unnamed and repeated objects

Designer ES2 supports the capability to create both unnamed objects and multiple objects with the same name. You can still create calcula-
tions and scripts to access and modify properties and values of unnamed objects by using the number sign (#) notation and object occur-
rence values using the square bracket ([ ]) notation. FormCalc correctly interprets the number sign (#) and square bracket ([ ]) characters;
however, JavaScript does not. To access the value of a text field in a situation where the number sign (#) or square brackets ([ ]) occur, using
JavaScript, you must use the resolveNode method in conjunction with either a fully qualified reference syntax or an abbreviated reference
syntax.
For example, when you create a new blank form, by default, the name of the subform that represents the page of the form is an unnamed
subform with an occurrence value of 0. The following illustration shows the form hierarchy on a new form with default object naming.

The untitled subform that represents the first page of the form has an occurrence number of 0. In this situation, both of the following
reference syntaxes access the value of the text field in the form hierarchy above on a new form that uses default naming conditions:
xfa.form.form1.#subform.TextField1.rawValue
xfa.form.form1.#subform[0].TextField1.rawValue

Note: By default, if you do not specify an occurrence value for an object, the reference syntax accesses the first occurrence of that object.
FormCalc recognizes the fully qualified reference syntax above and interprets it directly. To access the same value by using JavaScript, you
must use one of these forms of the resolveNode scripting method:
xfa.resolveNode("xfa.form.form1.#subform.TextField1").rawValue;
xfa.resolveNode("xfa.form.form1.#subform[0].TextField1").rawValue;

If you add a new page to your form, by default, the name of the subform that represents the new page is unnamed; however, the occurrence
value for the new subform is set to 1. You can specify the new unnamed subform by using a similar reference syntax as above:
 LIVECYCLE DESIGNER ES2 61
Referencing Objects in Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

xfa.form.form1.#subform[1].TextField1.rawValue // FormCalc
xfa.resolveNode("xfa.form.form1.#subform[1].TextField1").rawValue; // JavaScript

Note: The statement completion options available in the Script Editor include unnamed objects at the beginning of the list. Objects that have
multiple occurrence values appear only once in the list, representing the first occurrence of the object. If you want to access an occurrence value
other that the first occurrence, you must manually add the occurrence value to the reference syntax.
You can use the resolveNode method to reference objects within other reference syntax statements. This can help to reduce the amount of
scripting you need to reference a particular object, property, or method. For example, you could simplify the reference syntax that points to
a text field on the second page of your form to the following statement:
xfa.form.form1.resolveNode("#subform[1].TextField1").rawValue; // JavaScript

Referencing the current object

If you want to change properties or values of the current object using calculations or scripts attached to the object itself, both FormCalc and
JavaScript use unique shortcuts to reduce the size of the reference syntax. FormCalc uses the number sign ($) character to denote the current
object, and JavaScript uses the keyword this.
For example, the following reference syntax returns the value of the current object:
$ // FormCalc
this.rawValue // JavaScript

Similarly, you can use the dollar sign ($) shortcut and the keyword this to replace the name of the current object when accessing object
properties in calculations and scripts. For example, the following reference syntax changes the tool tip text associated with the current object:
$.assist.toolTip.value = "This is some tool tip text." // FormCalc
this.assist.toolTip.value = "This is some tool tip text."; // JavaScript

FormCalc reference syntax shortcuts

To make accessing object properties and values easier, FormCalc includes shortcuts to reduce the effort required to create references. The
following table outlines the reference syntax shortcuts for FormCalc.

Notation Description

$ Refers to the current field or object, as shown in this example:

$ = "Tony Blue"

The above example sets the value of the current field or object to Tony Blue.

$data Represents the root of the data model xfa.datasets.data. For example,

$data.purchaseOrder.total

is equivalent to

xfa.datasets.data.purchaseOrder.total

$event Represents the current form object event. For example,

$event.name

is equivalent to

xfa.event.name

$form Represents the root of the form model xfa.form. For example,

$form.purchaseOrder.tax

is equivalent to stating

xfa.form.purchaseOrder.tax
 LIVECYCLE DESIGNER ES2 62
Referencing Objects in Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Notation Description

$host Represents the host object. For example,

$host.messageBox("Hello world")

is equivalent to

xfa.host.messageBox("Hello world")

$layout Represents the root of the layout model xfa.layout. For example,

$layout.ready

is equivalent to stating

xfa.layout.ready

$record Represents the current record of a collection of data, such as from an XML file. For example,

$record.header.txtOrderedByCity

references the txtOrderedByCity node within the header node of the current XML data.

$template Represents the root of the template model xfa.template. For example,

$template.purchaseOrder.item

is equivalent to

xfa.template.purchaseOrder.item

! Represents the root of the data model xfa.datasets. For example,

!data

is equivalent to

xfa.datasets.data

* Selects all form objects within a given container, such as a subform, regardless of name, or selects all objects that have
a similar name.

For example, the following expression selects all objects named item on a form:

xfa.form.form1.item[*]

You can use the ‘*’ (asterisk) syntax with JavaScript if it used with the resolveNode method. For more information
about the resolveNode method, see Designer ES22 Help, or see LiveCycle Designer ES2 Scripting Reference.
 LIVECYCLE DESIGNER ES2 63
Referencing Objects in Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Notation Description

.. You can use two dots at any point in your reference syntax to search for objects that are a part of any subcontainer of
the current container object, such as a subform. For example, the expression Subform_Page..Subform2 means
locate the node Subform_Page (as usual) and find a descendant of Subform_Page called Subform2.

Using the example tree above,

Subform_Page..TextField2

is equivalent to

Subform_Page.Subform1[0].Subform3.TextField2[0]

because TextField2[0] is in the first Subform1 node that FormCalc encounters on its search. As a second
example,

Subform_Page..Subform3[*]

returns all four TextField2 objects.

You can use the ‘..’ (double period) syntax with JavaScript if it used with the resolveNode method. For more informa-
tion about the resolveNode method, see Designer ES22 Help, or see LiveCycle Designer ES2 Scripting Reference.

# The number sign (#) notation is used to denote one of the following items in a reference syntax:

• An unnamed object. For example, the following reference syntax accesses an unnamed subform:

xfa.form.form1.#subform

• Specify a property in a reference syntax if a property and an object have the same name. For example, the following
reference syntax accesses the name property of a subform if the subform also contains a field named name:

xfa.form.form1.#subform.#name

You can use the ‘#’ (number sign) syntax with JavaScript if it used with the resolveNode method. For more information
about the resolveNode method, see Designer ES22 Help, or see LiveCycle Designer ES2 Scripting Reference.
 LIVECYCLE DESIGNER ES2 64
Referencing Objects in Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Notation Description

[ ] The square bracket ([ ]) notation denotes the occurrence value of an object. To construct an occurrence value refer-
ence, place square brackets ([ ]) after an object name, and enclose within the brackets one of the following values:

• [ n ], where n is an absolute occurrence index number beginning at 0. An occurrence number that is out of
range does not return a value. For example,

xfa.form.form1.#subform.Quantity[3]
refers to the fourth occurrence of the Quantity object.

• [ +/- n ], where n indicates an occurrence relative to the occurrence of the object making the reference. Positive
values yield higher occurrence numbers, and negative values yield lower occurrence numbers. For example,

xfa.form.form1.#subform.Quantity[+2]

This reference yields the occurrence of Quantity whose occurrence number is two more than
the occurrence number of the container making the reference. For example, if this
reference was attached to the Quantity[2]object , the reference would be the same as

xfa.template.Quantity[4]

If the computed index number is out of range, the reference returns an error.

The most common use of this syntax is for locating the previous or next occurrence of a
particular object. For example, every occurrence of the Quantity object (except the first)
might use Quantity[-1] to get the value of the previous Quantity object.

• [*] indicates multiple occurrences of an object. The first named object is found, and objects of the same name
that are siblings to the first are returned. Note that using this notation returns a collection of objects. For example,

xfa.form.form1.#subform.Quantity[*]

• This expression refers to all objects with a name of Quantity that are siblings to the first occurrence of
Quantity found by the reference.

In language-specific forms for Arabic, Hebrew, Thai, and Vietnamese, the reference syntax is always on the right (even
for right-to-left languages).
 LIVECYCLE DESIGNER ES2 65
Referencing Objects in Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Notation Description

[ ]
(Continued)

Using the tree for reference, these expressions return the following objects:

• Subform_Page.Subform1[*] returns both Subform1 objects.

• Subform_Page.Subform1.Subform3.TextField2[*] returns two TextField2 objects.

Subform_Page.Subform1 resolves to the first Subform1 object on the left, and TextField2[*] evaluates
relative to the Subform3 object.

• Subform_Page.Subform1[*].TextField1 returns both of the TextField1 instances.

Subform_Page.Subform1[*] resolves to both Subform1 objects, and TextField1 evaluates relative to
the Subform1 objects.

• Subform_Page.Subform1[*].Subform3.TextField2[1] returns the second and fourth TextField2

objects from the left. Subform_Page.Subform1[*] resolves to both Subform1 objects, and
TextField2[1] evaluates relative to the Subform3 objects.

• Subform_Page.Subform1[*].Subform3[*] returns both instances of the Subform3 object.

• Subform_Page.* returns both Subform1 objects and the Subform2 object.

• Subform_Page.Subform2.* returns the two instances of the NumericField2 object.

You can use the ‘[ ]’ (square bracket) syntax with JavaScript if it used with the resolveNode method. For more infor-
mation about the resolveNode method, see Designer ES22 Help, or see LiveCycle Designer ES2 Scripting Reference.
 66

8. Creating and Reusing JavaScript Functions

The script object is an object you can use to store JavaScript functions and values separately from any particular form object. Typically, you
use the script object to create custom functions and methods that you want to use as part of JavaScript scripts in many locations on your
form. This technique reduces the overall amount of scripting required to perform repetitive actions.
The script object only supports script written in JavaScript; however, there are no restrictions on the location where the scripts are executed,
provided that the scripting language for the event that invokes the script object is set to JavaScript. Both Acrobat and Forms ES2 process
scripting from a script object in the same manner, but both are also distinct. Only scripts set to run on the client can make use of script
objects set to run on the client, and vice versa.

To create a script object

There are two parts to creating a script object. The first part involves adding the object to the form design, and the second part is writing
the script you want to store in the script object.
1 Create a new form or open an existing form.
2 In the Hierarchy palette, right-click either a form-level object or a subform-level object and select Insert Script Object.

A. Form level object B. Subform level object C. Subform level script object D. Form level script object

3 (Optional) Right-click the script object and select Rename Object.

To add script to a script object

After you have a script object on your form, you can add scripts using the Script Editor.
1 Select the script object in the Hierarchy palette.
The Script Editor is displayed with both a Script Object value in the Show list and a JavaScript value in the Language list. You cannot
change either of these values.
 LIVECYCLE DESIGNER ES2 67
Creating and Reusing JavaScript Functions LiveCycle Designer ES2 Scripting Basics

2 Enter your script in the Script Source field.

3 Click the Preview PDF tab to test the form.

Example
For example, create a script object called feedback that contains the following function:
function emptyCheck(oField) {

if ((oField.rawValue == null) || (oField.rawValue == "")) {

xfa.host.messageBox("You must input a value for this field.", "Error Message", 3);
}
}

To reference JavaScript functions stored in a script object

After you add scripts to a script object, you can reference the script object from any event that supports JavaScript scripts.
1 Select an object on your form and select an event from the Show list.
2 Create a reference to the script object and any functions within the script object. The following generic syntax assumes that the object
where you are referencing the script object is at the same level as the script object in the form hierarchy or that the script object exists at
the highest level of the form hierarchy.
script_object.function_name(parameter1, ...);
3 Apply the new script to the form object and test it by previewing the form using the Preview PDF tab.
Similar to referencing other objects on a form, you must provide a valid syntax when referencing the script object that includes where it
exists within the form hierarchy. For more information about referencing objects in scripting, see “Referencing object properties and values”
on page 58.

Example
For example, using the script object example from “To add script to a script object” on page 66, place the following JavaScript script on the
exit event for a text field. Test the form using the Preview PDF tab.

feedback.emptyCheck(this)
 68

9. Using Script Fragments

A script fragment contains a script object. A script object contains reusable JavaScript functions or values that are stored separately from
any particular form object, such as a date parser or a web service invocation. Typically, you use the script objects to create custom functions
and methods that you want to use in many locations on a form. Using script objects reduces the overall amount of scripting required to
perform repetitive actions.
Script fragments include only script objects that appear as children of variables in the Hierarchy palette. Fragments cannot contain scripts
that are associated with other form objects, such as event scripts like validate, calculate, or initialize.
You create a script fragment from the Hierarchy palette. For more information, see “To create a script fragment” on page 68.
You edit script fragments the same way as other fragments.

Script fragment properties

When you select a script fragment, the Script Object tab in the Object palette displays the fragment properties.

Source File
Sets the source file for the fragment reference. This property is visible only when the selected object is a fragment reference.

Fragment Name
Sets the name of the fragment. You can click the Frag Info button to view the fragment information.
This property is visible when a fragment reference or a fragment that is defined in a source file is selected. When the selected object is a
fragment reference, this property does not appear if the source file is not specified. The Fragment Name list includes all the fragments in the
specified source file. The Custom option directly supports setting a SOM expression or an ID value as the fragment reference and supports
the implementation in the XML Forms Architecture.

To create a script fragment

You can create a script fragment of common functions that you can reuse in multiple forms. To create a script fragment, you create a script
object that contains the functions that you want to reuse in multiple form designs. The script fragment can include only one script object.
1 Create a script object.
2 In the Hierarchy palette, right-click the script object and select Fragments > Create Fragment.
Note: You can also create a script fragment by dragging the script object from the Hierarchy palette to the Fragment Library palette.
3 To use a different fragment name, in the Name box, type a name for the fragment.
4 (Optional) In the Description box, type a description of the fragment.
5 Select a method for creating the fragment:
• To define the fragment in a separate XDP file that is stored in the Fragment Library, select Create New Fragment In Fragment
Library. In the Fragment Library list, select the Fragment Library in which to save the fragment file. To use a different file name, in
the File Name box, type the file name for the fragment. If you do not want to replace the selection with the new fragment, deselect
Replace Selection With Reference To New Form Fragment.
• To define the fragment in the current file, select Create New Fragment in Current Document.
6 Click OK.
 LIVECYCLE DESIGNER ES2 69
Using Script Fragments LiveCycle Designer ES2 Scripting Basics

To insert a script fragment

You can use script fragments to reuse JavaScript functions in multiple forms. When creating a form design, you insert a reference to an
existing script fragment and the fragment appears in the form design.
You cannot insert a fragment in an XFAF document.
Note: To preview the fragments in the Fragment Library palette, select Show Preview Pane from the palette menu.

To insert a script fragment from the Fragment Library palette:

1 In the fragment library, select the script fragment.
2 Drag the fragment to a subform or variables object in the Hierarchy palette.

To insert a script fragment from the Insert menu:

1 Select Insert > Fragment.
2 Navigate to the file that contains the fragment.
3 Select the file and click OK. The fragment appears as a child of the variables object in the root subform
 70

10. Debugging Calculations and Scripts

Designer ES2 includes various features and strategies for debugging calculations and scripts, depending on the scripting language you
choose.
For JavaScript language script debugging, you can use the alert or the messageBox methods to provide debugging feedback. One disad-
vantage of this method is that you must close many message boxes. Another problem is that displaying a message box can cause differences
in the form’s behavior, especially if you are trying to debug a script that is setting focus to an object on your form. It is best to use
console.println to output text to the JavaScript Console from Acrobat to debug a form.

Designer ES2 Report palette warning and validation messages

The Report palette provides warning and validation messages to help you debug a form as you design it. The Warning tab lets you view errors
or messages that Designer ES2 generated as you design a form. The Log tab lets you view the following errors and messages:
• Validation messages
• JavaScript or FormCalc scripting execution errors
• Design-time form rendering errors that are generated when you import or save a form or preview a form from the Preview PDF tab.
For more information about using the Report palette, see “Using the workspace to debug calculations and scripts” on page 14.

Providing debugging feedback using the messageBox method

The XML Form Object Model messageBox method lets you output information from an interactive form into a dialog box at run time. You
can take advantage of the XML Form Object Model messageBox method to display messages or field values at runtime. When initiated, the
messageBox method displays a string value in a new client application dialog box. The string value can be a text message that you create for
debugging purposes or the string value of fields or expressions.
For example, consider a scenario with a simple form design that contains a single numeric field (NumericField1) and a button (Button1). In
this case, the following FormCalc calculation and JavaScript script each output a message displaying some text and the value currently
displayed in the numeric field. By adding either the calculation or the script to the click event of the button object, you can interactively
display the value of the numeric field in a new dialog box by clicking the button.

FormCalc
xfa.host.messageBox(Concat("The value of NumericField1 is: ",
NumericField1), "Debugging", 3)

JavaScript
xfa.host.messageBox("The value of NumericField1 is: " +
NumericField1.rawValue, "Debugging", 3);

Caution: The messageBox method returns an integer value representing the button that the form filler selects in the message box dialog. If you
attach the messageBox method to the calculate event of a field object, and the messagebox method is the last line of the script, the field
displays the return value of the messageBox method at runtime.

Output information into a text field

You can output information, such as field values or messages, into a text field on your form design. For example, you can append new
messages or values to the value of a text field to create a log for future reference..
 LIVECYCLE DESIGNER ES2 71
Debugging Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

JavaScript Debugging
If you use the JavaScript language for a script, you can use the console.println("string") function to output information to the JavaS-
cript Console available in Acrobat Professional. Alternatively, yu can use the alert method from the Acrobat JavaScript Object Model to
debug JavaScript.

JavaScript Debugger in Acrobat Professional

The JavaScript Debugger in Acrobat Professional lets you test JavaScripts scripts. The debugger includes the JavaScript Console, where you
can test portions of JavaScript code in the Preview PDF tab. The JavaScript Console provides an interactive and convenient interface for
testing portions of JavaScript code and experimenting with object properties and methods. Because of its interactive nature, the JavaScript
Console behaves as an editor that supports the execution of single lines or blocks of code.
To enable the JavaScript Debugger for Designer ES2 and execute code from the JavaScript Console, enable JavaScript and the JavaScript
Debugger in Acrobat Professional.
Note: You can enable the JavaScript Debugger in Adobe Reader if you have Reader Extensions ES2 installed. To enable the JavaScript Debugger
in Adobe Reader, you must get the debugger.js file and then edit the Microsoft Windows Registry. For more information about enabling the
JavaScript Debugger in Adobe Reader, see Developing Acrobat Applications Using JavaScript (English only).

To enable the JavaScript Debugger for Designer ES2

1 Start Designer ES2.
2 Start Acrobat Professional.
3 In Acrobat Professional, select Edit > Preferences.
4 Select JavaScript from the list on the left.
5 Select Enable Acrobat JavaScript if it is not already selected.
6 Under JavaScript Debugger, select Enable JavaScript Debugger After Acrobat Is Restarted.
7 Select Enable Interactive Console. This option lets you evaluate code that you write in the JavaScript Console.
8 Select Show Console On Errors And Messages. This option ensures that if you make mistakes, the JavaScript Console displays helpful
information.
9 Click OK to close the Preferences dialog box.
10 Quit Acrobat Professional.
11 In Designer ES2, click the Preview PDF tab.
12 Press Ctrl+J to open the JavaScript Debugger.

To prevent the JavaScript Debugger from disappearing in Designer ES2

If the JavaScript Debugger from Acrobat is active and it disappears when you click components in the Designer ES2 interface, stop the
Acrobat.exe process in the Microsoft Windows Task Manager. The Acrobat.exe process continues to run after Acrobat is closed so that
Acrobat is displayed faster if it is restarted. Stopping the process ends the association between the JavaScript Debugger and the
Acrobat Professional session so that you can use the JavaScript Debugger in Designer ES2.
1 In the Windows Task Manager, click the Processes tab.
2 In the Image Name column, right-click Acrobat.exe and select End Process.

Evaluating code using the JavaScript Console

There are three ways evaluate single and multiple lines of code using the JavaScript Console from Acrobat.

To evaluate a portion of a line of code

❖ Highlight the portion in the console window and press either Enter on the numeric keypad or Ctrl+Enter on the regular keyboard.
 LIVECYCLE DESIGNER ES2 72
Debugging Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

To evaluate a single line of code

❖ Place the cursor is in the appropriate line in the console window and press Enter on the numeric keypad or Ctrl+Enter on the regular
keyboard.

To evaluate multiple lines of code

❖ Highlight those lines in the console window and press either Enter on the numeric keypad or Ctrl+Enter on the regular keyboard.

To delete content that appear in the JavaScript Console

❖ Click Clear in the console window.
The result of the most recently evaluated JavaScript script is displayed in the console window.
After evaluating each JavaScript script, the console window prints out undefined, which is the return value of the statement. Notice that
the result of a statement is not the same as the value of an expression within the statement. The return value undefined does not mean that
the value of script is undefined; it means that the return value of the JavaScript statement is undefined.

Providing debugging feedback to the JavaScript Console

If you are creating scripts using JavaScript, you can output messages to the JavaScript Console from Acrobat at runtime by using the
console.println method included with the JavaScript Object Model from Acrobat. When initiated, the console.println method
displays a string value in the JavaScript Console. The string value can be a text message that you create for debugging purposes or the string
value of fields or expressions.
For example, consider a simple form design that contains a single numeric field (NumericField1) and a button (Button1). In this case, the
following JavaScript script outputs a message displaying some text and the value currently displayed in the numeric field. By adding either
the calculation or the script to the click event of the button object, you can interactively display the value of the numeric field in a new
dialog box by clicking the button.
console.println("The value is: " + NumericField1.rawValue);

For more information about the console.println method and the JavaScript Object Model from Acrobat, see Developing Acrobat Appli-
cations Using JavaScript (English only).
For more information about the JavaScript Console and the JavaScript Debugger, see Developing Acrobat Applications Using JavaScript
(English only).

Providing debugging feedback using the alert method

If you want to return a message box during a calculate event, you can take advantage of the alert method from the JavaScript Object
Model from Acrobat. For example, the following script returns the value of a text field:
var oField = xfa.resolveNode("TextField1").rawValue;
app.alert(oField);

For more information about the alert method and the JavaScript Object Model from Acrobat, see Developing Acrobat Applications Using
JavaScript (English only).

Debugging tips
Remember the following tips when debugging calculations and scripts.

Sample data
Remember to specify a preview data file in the Form Properties dialog box. Specifying a preview data file does not save the data into the
final PDF.
 LIVECYCLE DESIGNER ES2 73
Debugging Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Master pages
To debug master pages, drop a different object on each master page to find out which one is specified.

First page in a form

Designer ES2 looks at the root subform to determine which page to begin the form on. If the root subform does not determine the first page,
the first master page is used by default.

Incremental debugging
When debugging a form design, start by removing pieces of the form until you cannot reproduce the problem. Try to isolate the source of
the problem after you've reviewed every script and object property. To debug subforms, you can specify a thick colored border around the
subform, or use a fill. Colors or fill can help indicate which subform is used and its span. Usually, this technique works well when you want
to determine the bounds of an object and can show why it is placed in a certain location.

Hierarchy view
View your form design by using the Hierarchy view to get a better understand of it. The order of the objects that are listed in the hierarchy
indicates the order they are placed on the page. Some objects are not clickable if they are below one another.

Script error messages

In Designer ES2, script error messages appear on the Log tab of the Report palette when you preview the form. If the form design contains
FormCalc scripts and the error occurs on the server, the warnings appear in the Log tab. If the FormCalc script error occurs on the client,
the message appears in Adobe Reader or Acrobat.
An error in a FormCalc script prevents the entire script from executing.
An error in a JavaScript executes until it reaches the error.

Syntax errors in FormCalc

Syntax errors in FormCalc are sometimes difficult to solve. When the "Syntax error near token '%1' on line %2, column %3" appears, %1
usually contains the token (word) nearest to the error. Therefore the token is possibly correct and the error is not related to the error other
than its proximity to it. For example, the following script generates the 7008 error: "Syntax error near token 'then' on line x, column y."
var b = abc(1)
if (b ne 1) then
//comment

The problem is that an endif token is missing from the script. The last correct token is then (comments do not count as tokens). Adding
an endif statement to the end of the script fixes the problem.

Functions defined in a script object

You can only call a function that is defined in a script object with a JavaScript script. Make sure that you change the script language to JavaS-
cript in the Script Editor. If not, you may see a message indication that Designer ES2 cannot resolve the script object. The same error can
occur when a syntax issue occurs in the script object.

Web service calls

When creating web service calls, use the postExecute event to see what was returned and whether the web service issued any error messages.

Long SOM expressions

When typing long, multilayered SOM expression, press the Ctrl key and click the object on the canvas. The command inserts the object's
SOM expression into the script. The SOM expression is relative to the object hosting the script. To insert the absolute SOM, press Ctrl+Shift
and click the object. These commands work when you click objects in the Design view, not in the Hierarchy view.
 LIVECYCLE DESIGNER ES2 74
Debugging Calculations and Scripts LiveCycle Designer ES2 Scripting Basics

Test SOM expressions

When a long SOM expression fails, start back at the root of the expression and test each dot with className until you reach the problem.
For example, test a.b.c.d by starting at the root:
• console.println(a.className)
• console.println(a.b.className)
• console.println(a.b.c.className)
• console.println(a.b.c.d.className)

Use script objects to debug form designs

Use a script object, such as a fragment, to help you debug form designs:
• Dump out a node hierarchy under a node.
• Output the value of a property or attribute of a node.
• Output whether a node has a property or attribute specified.
• Output the SOM expression of a node.
• Dump out the xml src of a given node.
Here is an example of a script object that contains several debugging functions:
<script contentType="application/x-javascript" name="XFADEBUG">
//This script object provides several tracing functions to help debug a form design
//Dump out node hierarchy to console.println()
function printNode(node) {... }
//Dump out SOM expression to console.println() function printSOM(node) {... }
//Dump out property or attribute value function printValue(node, attrOrPropertyName) {...}
function printXMLSource(node) { ....}
function printHasPropertySpecified(node, prop) {...}\\
</script>

Things to avoid when building forms

• Calling xfa.layout.relayout(). on the docReady even causes problems because the docReady event triggers every time the layout
is ready.
• Placing a flowed container inside a positioned container causes problems with page breaks, overlapping objects, and repeating subforms.
The root subform is a flowed container. Take advantage of it and place your flowable containers inside the root subform by unwrapping
the page subforms after your layout is done. Alternatively, set the flow of the page subforms to flowed.
• Blank page issue (Acrobat 7.1 or earlier). At design time, a blank page is displayed when the subform does not fit within the boundaries
of the content area. To fix the blank page, either resize the subform or allow it to break between pages. If a user is using Acrobat 7.1 or
earlier, the second-level subform appears on a different page.
 75

11. Working with a Host Application

A host application is the application in which a form exists at any given time. For example, if you are using Forms ES2 to render a form in
HTML format, then during the pre-rendering process the host application is Forms ES2. Once you render a form and view it in a client appli-
cation such as Acrobat, Adobe Reader, or an HTML browser, then the client application becomes the host application.
Designer ES2 includes a scripting model that provides scripting properties and methods for directly interfacing with a hosting application.
For example, you can use the properties and methods in the host scripting model to provide PDF page navigation actions in Acrobat or
Adobe Reader, or you can use the importData method to load data into your form.
You can reference the host script model syntax on any valid scripting event for form design objects using the following syntax for both
FormCalc and JavaScript:
xfa.host.property_or_method

Host scripting model properties and methods

Using the host scripting model properties and methods, you can retrieve information and execute actions that are not otherwise accessible
through calculations and scripts. For example, you can retrieve the name of the host application (such as Acrobat), or advance the current
page on an interactive form. The following table lists the properties and methods that are available for the host scripting model.

Properties Methods

appType beep
calculationsEnabled exportData
currentPage gotoURL
language importData
name messageBox
numPages pageDown
platform pageUp
title print
validationsEnabled resetData
variation response
version setFocus

For more information about the host scripting model properties and methods, see the LiveCycle ES2 Developer Center located at
www.adobe.com/devnet/livecycle/.

Comparing the host scripting model functionality

This table lists the Designer ES2 host scripting model properties and methods, and compares them to the equivalent expressions in the
JavaScript Object Model in Acrobat.
For more information about the host scripting model properties and methods, see Designer ES2 Help, or see the Designer ES2 Scripting
Reference.

Host scripting model properties and methods JavaScript Object Model from Acrobat equivalent

xfa.host.appType app.viewerType

xfa.host.beep( [ INTEGER param ] ) app.beep([ nType ])

xfa.host.currentPage doc.pageNum

xfa.host.exportData([ STRING param1 [, doc.exportXFAData(cPath [, bXDP ])

BOOLEAN param2 ] ])
 LIVECYCLE DESIGNER ES2 76
Working with a Host Application LiveCycle Designer ES2 Scripting Basics

Host scripting model properties and methods JavaScript Object Model from Acrobat equivalent

xfa.host.gotoURL( STRING param1 ) doc.getURL(cURL, [ bAppend ])

or

app.launchURL(URL);

xfa.host.importData( [ STRING param ] ) doc.importXFAData(cPath)

xfa.host.language app.language

xfa.host.messageBox(STRING param1 [, app.alert(cMsg [, nIcon [, nType [,

STRING param2 [, INTEGER param3 [, cTitle ] ] ])
INTEGER param4 ] ] ])

xfa.host.name none

xfa.host.numPages doc.numPages

xfa.host.pageDown() doc.pageNum++

xfa.host.pageUp() doc.pageNum--

xfa.host.platform app.platform

xfa.host.print(BOOLEAN param1, INTEGER doc.print([ bUI [, nStart [, nEnd [,

param2, INTEGER param3, BOOLEAN bSilent [, bShrinkToFit [,
param4, BOOLEAN param5, BOOLEAN bPrintAsImage [, bReverse [,
param6, BOOLEAN param7, BOOLEAN bAnnotations ] ] ] ] ] ] ] ])
param8)

xfa.host.resetData( [ STRING param ] ) doc.resetForm([ aFields ])

xfa.host.response( STRING param1 [, app.response(cQuestion [, cTitle [,

STRING param2 [, STRING param3 [, cDefault [, bPassword ] ] ])
BOOLEAN param4] ] ])

xfa.host.setFocus( STRING param ) field.setFocus()

(Deprecated)

xfa.host.title doc.title

xfa.host.variation app.viewerVariation

xfa.host.version app.viewerVersion
 77

12. Working with the Event Model

The event model stores object event properties. These properties are useful if you want to access values that are otherwise out of the scope
of the events listed in the Show list within the Script Editor.
The event model controls the changes in a form that occur before, during, and after actions take place. These actions include dynamic form
events, such as the point when the data and form design are merged but before pagination is applied, and also interactive form events, such
as when a user updates the value of a field.

Event model properties and methods

Using the event object properties and methods, you can retrieve information and execute actions that otherwise are not accessible through
calculations and scripts. For example, you can retrieve the full value of a field that otherwise would have part of the data stripped out because
it is too long or otherwise invalid. Retrieving the full value of a field is useful in situations where you have to do extensive error checking.

Properties Methods

change emit
className reset
commitKey
fullText
keyDown
modifier
name
newContentType
newText
prevContentType
prevText
reenter
selEnd
selStart
shift
soapFaultCode
soapFaultString
target

For more information about the event scripting model properties and methods, see the Adobe Designer ES2 Developer Center located at
www.adobe.com/devnet/livecycle/designing_forms.html.
 78

13. Moving from Scripting in Acrobat to

Designer ES2
Designer ES2 includes extensive scripting capabilities, including support for the most common JavaScript objects from Acrobat. When you
convert an Acrobat form to Designer ES2, most JavaScript scripts continue to work without requiring changes. However, you will need to
manually convert some JavaScript scripts from Acrobat to maintain the behavior of your Acrobat form.
When converting scripts on your Acrobat form, note that Designer ES2 scripting differs from scripting in Acrobat in several ways:
Designer ES2 workspace In the Designer ES2 workspace, you can change object properties and behaviors on your form without requiring
you to create scripts.
Scripting languages Designer ES2 includes support for JavaScript as well as for FormCalc, which is a simple calculation language.
FormCalc includes built-in functions that perform many useful operations that would otherwise require extensive scripting.
Referencing objects, properties, and methods Designer ES2 forms are highly structured; therefore, to reference specific objects,
properties, or methods, you must include the appropriate reference syntax in your script. You can use the statement completion options in
the Script Editor to assist you in creating reference syntaxes.
It is possible to continue to use JavaScript objects, properties, and methods from Acrobat in Designer ES2. However, you should consider
JavaScript from Acrobat only for tasks that you cannot perform using the XML Form Object Model in Designer ES2. For example, you can
use JavaScript from Acrobat to add attachments, bookmarks, and annotations; search or spell check the form; create reports; or access and
manipulate metadata. You cannot use JavaScript from Acrobat to perform actions such as setting field values, adding new fields to a form,
or deleting pages from a form.
Note: You cannot use Acrobat to add JavaScript scripts to a Designer ES2 form, including Acrobat forms that you have converted using
Designer ES2. When you view a Designer ES2 form in Acrobat, all JavaScript tools are unavailable.
For more information about converting Acrobat scripting to Designer ES2, see the article Converting Acrobat JavaScript for Use in
Designer ES2 Forms in the LiveCycle ES2 Developer Center.

Converting Acrobat forms that contain scripts

One of the first steps in converting a form from Acrobat to Designer ES2 is to determine how much of the Acrobat scripting is supported
by Designer ES2 and how much you must convert.
In general, you should convert all Acrobat scripting to an equivalent in Designer ES2. Designer ES2 scripting takes full advantage of the
highly structured nature of Designer ES2 forms, as well as useful forms-specific functionality, to make designing and implementing your
forms solution faster and easier.
The Acrobat scripting you should retain include those that deal with the form’s environment and peripheral operations, such as adding
attachments or multimedia, performing searches, or creating reports and handling document metadata.
For more information about converting Acrobat scripting to Designer ES2, see the article Converting Acrobat JavaScript for Use in
Designer ES2 Forms in the Designer ES2 Developer Center.

Using JavaScript objects from Acrobat in Designer ES2

In Designer ES2, you can script against certain JavaScript objects in Acrobat by using the Acrobat scripting syntax. As a result, you can use
the properties and methods of those objects on your form. For example, to display a message in the JavaScript Console from Acrobat, you
can add the following script to the event of a form design object in Designer ES2:
console.println("This message appears in the JavaScript Console.");
 LIVECYCLE DESIGNER ES2 79
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

You can also have the form send itself by email by adding the following script to the click event of a button:
var myDoc = event.target;
myDoc.mailDoc(true);

Note: In Designer ES2, you must ensure that the scripting language for the event is set to JavaScript so that the script will execute correctly at
run time.
You can also use references to the JavaScript objects in Acrobat in your reference syntax. For example, the following script gets the signed
state of a signature field and takes an action based on the state:
// Proceed if the current field is not signed.
var oState =
event.target.getField("form1[0].#subform[0].SignatureField1[0]")
.signatureValidate(); //Get the field's signed state.

if (oState == 0) {
...
}

Note: This example uses a fully qualified reference syntax to reference the text For more information about referencing form design objects, see
“Referencing object properties and values” on page 58.
When working with JavaScript from Acrobat in Designer ES2, remember these points:
• In Designer ES2, use event.target to access the Doc JavaScript object from Acrobat. In Acrobat, the this object is used to reference
the Doc object; however, in Designer ES2, the this object refers to the form design object to which the script is attached.
• The Script Editor has no statement completion for JavaScript objects from Acrobat. See the JavaScript for Acrobat API Reference.
• The Doc method event.target.importTextData("file.txt") is not supported for dynamic XFA forms that have been certified.
For more information about converting Acrobat scripting to Designer ES2, see the article Converting Acrobat JavaScript for Use in
Designer ES2 Forms in the LiveCycle ES2 Developer Center.

JavaScript objects from Acrobat supported in Designer ES2

The following table lists the availability of the most commonly used Acrobat objects, properties, and methods in Designer ES2, and provides
information on any equivalent functionality in Designer ES2. Although the table contains the most commonly used Acrobat objects,
properties and methods, some are not listed, such as multimedia objects, because they are rarely used for forms.
In cases where no equivalent Designer ES2 functionality is listed, no direct Designer ES2 property or method can reproduce the Acrobat
behavior. However, you can still create custom functions or scripts to replicate the Acrobat capability.

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

Annot object properties and methods

All properties and methods Yes None Only forms with a fixed layout support
the annotation layer.

app object properties

calculate No None Designer ES2 includes the

execCalculate method which
initiates the calculate event.

language Yes xfa.host.language See the language property.

monitors Yes None

platform Yes xfa.host.platform See the platform property.

 LIVECYCLE DESIGNER ES2 80
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

plugins Yes None

toolbar Yes None

viewerType Yes xfa.host.appType See the appType property.

viewerVariation Yes xfa.host.variation See the variation property.

viewerVersion Yes xfa.host.version See the version property.

app object methods

addMenuItem Yes None

addSubMenu Yes None

addToolButton Yes None

alert Yes xfa.host.messageBox() See the messageBox method.

beep Yes xfa.host.beep() See the beep method.

browseForDoc Yes None

clearInterval Yes None

clearTimeOut Yes None

execDialog Yes None

execMenuItem Yes None Executes the specified menu command.

Use this method in Designer ES2 for File
menu commands.

getNthPluginName Yes None

getPath Yes None

goBack Yes None

goForward Yes None

hideMenuItem Yes None

hideToolbarButton Yes None

launchURL Yes None Designer ES2 includes the gotoURL

method that loads a specified URL into
the client application, such as Acrobat
or Adobe Reader.

listMenuItems Yes None

listToolbarButtons Yes None

mailGetAddrs Yes None

mailMsg Yes None

newDoc Yes None This method can only be executed

during batch, console, or menu events.

newFDF No None

openDoc Yes None

 LIVECYCLE DESIGNER ES2 81
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

openFDF No None

popUpMenuEx Yes None

popUpMenu Yes None

removeToolButton Yes None

response Yes xfa.host.response() See the response method.

setInterval Yes None

setTimeOut Yes None

trustedFunction Yes None

trustPropagatorFunction Yes None This method is only available during

batch, console, and application initial-
ization.

Bookmark object properties and methods

All properties and methods Yes None

doc object properties

author Yes None

baseURL Yes None

bookmarkRoot Yes None

calculate No None

dataObjects Yes None

delay No None

dirty Yes None This JavaScript script for Designer ES2

saves a copy of a form and tests whether
the form has changed:

var sOrigXML =
xfa.data.saveXML;
if (sOrigXML !=
xfa.data.saveXML)
{...}

disclosed Yes None

documentFileName Yes None

dynamicXFAForm Yes None

external Yes None

filesize Yes None

hidden Yes None

icons Yes None

keywords Yes None

layout Yes None

 LIVECYCLE DESIGNER ES2 82
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

media Yes None

metadata Yes xfa.form.desc See the desc object.

modDate Yes None

mouseX Yes None

mouseY

noautocomplete Yes None

nocache Yes None

numFields Yes xfa.layout.pageContent() The pageContent method returns a

list of all objects of a particular type.
However, you must execute the method
for design views and master pages to
scan the entire form.

numPages Yes xfa.host.numPages The numPages property returns the

page count for the rendered form in the
or
client. See also the absPageCount
xfa.layout.absPageCount() and pageCount methods.
xfa.layout.pageCount()

pageNum Yes xfa.host.currentPage See the currentPage property.

pageNum-- Yes xfa.host.currentPage-- See the currentPage property or the

pageUp method.
or

xfa.host.pageUp()

pageNum++ Yes xfa.host.currentPage++ See the currentPage property or the

pageDown method.
or

xfa.host.pageDown()

path Yes None

securityHandler Yes None

templates No None Use subform objects in Designer ES2,

and use properties and methods to add,
remove, move, and set subform
instances.

title Yes xfa.host.title See the title property.

doc object methods

addAnnot Yes None

addField No None You must use forms that have a fixed

layout in Designer ES2, and then use the
instanceManager object to add,
remove, and set the number of
instances of a particular object.

addIcon Yes None

addLink No None

addRecipientListCryptFilter Yes None

 LIVECYCLE DESIGNER ES2 83
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

addScript Yes None

addThumbnails No None

addWatermarkFromFile Yes None

addWatermarkFromText Yes None

addWeblinks Yes None

appRightsSign Yes None

appRightsValidate Yes None

bringToFront Yes None

calculateNow No xfa.form.recalculate(1); The recalculate method forces a

specific set of scripts on calculate
or
events to initiate. Boolean value indi-
execCalculate() cates whether True (default) - all
calculation scripts initiate; or False -
only pending calculation scripts initiate.

Designer ES2 calculate object

controls whether a form filler can over-
ride a field’s calculated value.

Alternatively, you can use the

execCalculate method for each
object for which you want to force a
recalculation.

closeDoc Yes None

createDataObject Yes None

createTemplate No None Designer ES2 forms do not have an

equivalent to the concept of an Acrobat
template. You must use subform objects
in Designer ES2.

deletePages No None In Designer ES2, you can use the

instanceManager object to remove
the subform object that represents a
page of your form.

embedDocAsDataObject Yes None

encryptForRecipients Yes None

encryptUsingPolicy Yes None

exportAsText Yes None This method is only available in the

JavaScript Console of the JavaScript
Debugger in Acrobat or during batch
processing.

exportAsFDF No xfa.host.exportData() The exportData method exports an

XML or XDP file instead of an FDF file.

exportAsXFDF No xfa.host.exportData() The exportData method exports an

XML or XDP file instead of an FDF file.

exportDataObject Yes None

 LIVECYCLE DESIGNER ES2 84
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

exportXFAData No xfa.host.exportData() The exportData method exports an

XML or XDP file instead of an FDF file.

extractPages No None

flattenPages Yes None

getAnnot Yes None

getAnnots Yes None

getDataObjectContents Yes None

getField("FieldName") Yes xfa.resolveNode The resolveNode method accesses

("FieldName") the specified object in the source XML of
the form.

getLegalWarnings Yes None

getLinks No None

getNthFieldName Yes You must loop through all objects with See the className property.
a similar class name until you reach the
nth occurrence.

getNthTemplate No None

getOCGs Yes None

getOCGOrder Yes None

getPageBox Yes None

getPageLabel Yes None

getPageNthWord Yes None

getPageNthWordQuads Yes None

getPageNumWords Yes None

getPageRotation Yes None

getPrintParams Yes None

getTemplate No None

getURL Yes xfa.host.gotoURL( See the gotoURL method.

"http://www.adobe.com");

gotoNamedDest No None

importAnFDF No None

importAnXFDF Yes None

importDataObject Yes None

importIcon Yes None

importTextData Yes None

importXFAData No xfa.host.importData See the importData method.

("filename.xdp");
 LIVECYCLE DESIGNER ES2 85
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

insertPages No None

mailDoc Yes None

mailForm No None

movePage No None

newPage No None

openDataObject Yes None

print Yes xfa.host.print(); See the print method.

removeDataObject Yes None

removeField No None

removeIcon Yes None

removeLinks No None

removeScript Yes None

removeTemplate No None

removeThumbnails No None

removeWeblinks Yes None

replacePages No None

resetForm No xfa.host.resetData() The resetData method resets all field

values on a form to the default values.
or
The reset method resets all properties
xfa.event.reset() within the event model.

saveAs Yes None In Designer ES2, the file must be saved

at the application level. These scripts are
examples of saving at the application
level:

app.executeMenuItem
("SaveAs");

or

var myDoc = event.target;

myDoc.saveAs();

spawnPageFromTemplate No None

setAction No None

setPageLabel Yes None

setPageRotation No None

setPageTabOrder No None In Designer ES2, select Edit > Tab Order

to set the tab order.

setScript No None

submitForm Yes Use one of the submit button objects in

Designer ES2.
 LIVECYCLE DESIGNER ES2 86
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

event object properties

change Yes xfa.event.change See the change property.

targetName Yes xfa.event.target See the target property.

field object properties

comb No None

charLimit No this.value.#text.maxChars In forms that have a fixed layout, char-

acter limit can be set in the Designer ES2
workspace. You can set fields on forms
whose layout expands to accommodate
all data.

display = display.noView No See “Changing the presence of a form You can also set the presence prop-
design object” on page 106. erty in the Designer ES2 workspace.

You cannot use the prePrint event to

change the presence of an object prior
to printing.

display = display.noPrint No See “Changing the presence of a form You can also set the presence prop-
design object” on page 106. erty in the Designer ES2 workspace.

You cannot use the prePrint event to

change the presence of an object prior
to printing.

defaultValue No None Set the default field value in the

Designer ES2 workspace.

exportValues No None Set the export value in the Designer ES2

workspace.

fillColor No xfa.form.Form1. See the fillColor property.

NumericField1.fillColor

hidden No this.presence = "invisible" You can also set the presence prop-
this. erty in the Designer ES2 workspace.
presence = "visible"

multiline No this.ui.textEdit.multiLine See the multiLine property.

= "1";

password No None Designer ES2 contains a Password Field

that you can use for passwords on a
form.

page No None Not applicable for Designer ES2 forms.

print No this.relevant = "-print"; See the relevant property.

radiosInUnison No None Grouped radio buttons in Designer ES2

are mutually exclusive by default.
 LIVECYCLE DESIGNER ES2 87
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

rect Yes You can get the height and width of a See the h, w, x, and y properties.
Designer ES2 form field by using the
following reference syntax:

this.h;
this.w;

Alternatively, you can retrieve the x and

y coordinates of an object using the
following reference syntax:

this.x;
this.y;

required No this.mandatory = "error"; See the mandatory and nullTest

properties.
or

this.validate.nullTest =
"error";

textColor No this.fontColor See the fontColor property.

textSize No this.font.size See the size property.

textFont No this.font.typeface See the typeface property.

value No this.rawValue See the rawValue property.

Designer ES2 fields have a value prop-

erty; it is not the equivalent of the
Acrobat value property.

field object methods

clearItems No DropDownList1.clearItems(); The clearItems method only applies

to Drop-down List and List Box objects
in Designer ES2.

deleteItemAt No None

getItemAt No None

insertItemAt No DropDownList1.addItem( See the addItem method.

.....)

isBoxChecked No if(CheckBox1.rawValue See the rawValue property.

== 1)....

isDefaultChecked No None

setAction No None Not applicable for Designer ES2 forms.

setFocus Yes xfa.host.setFocus The setFocus method requires that

("TextField1.somExpression") the specified object have a unique
name with respect to other objects on
your form.

setItems No None

setLock Yes None

signatureGetModifications Yes None

signatureGetSeedValue Yes None

signatureInfo Yes None

 LIVECYCLE DESIGNER ES2 88
Moving from Scripting in Acrobat to Designer ES2 LiveCycle Designer ES2 Scripting Basics

JavaScript in Acrobat Designer ES2 support JavaScript-equivalent in Comments

Designer ES2

signatureSetSeedValue Yes None

signatureSign Yes None

signatureValidate Yes None

search object method

search.query("<your text>"); Yes None The “..” (double period) FormCalc

shortcut syntax allows you to search for
objects within the XML Form Object
Model.

SOAP object method

All properties and methods Yes None

 89

14. Examples of Common Scripting Tasks

This chapter will contain examples of using JavaScript scripts to perform specific tasks or outcomes. Initially, several samples will be
included based on content that is posted to the Designer ES2 Developer Center, with the potential for more samples to be added in subse-
quent releases of this guide.
The samples that will be included for the first version of this guide are as follows:
• “Changing the background colors of fields, fillable areas, and subforms” on page 89
• “Hiding and showing objects” on page 91
• “Excluding an object from the tabbing order” on page 94
• “Changing the visual properties of an object on the client” on page 96
• “Getting the current or previous value of a drop-down list” on page 99
• “Preserving rich text formatting when copying field values” on page 100
• “Adjusting the height of a field at run time” on page 100
• “Setting a field as required at run time” on page 101
• “Calculating the field sums” on page 101
• “Highlighting fields in response to form filler interaction” on page 102
• “Resetting the values of the current subform” on page 105
• “Changing the presence of a form design object” on page 106
• “Using the properties of the instance manager to control subforms” on page 107
• “Using the methods of the instance manager to control subforms” on page 109
• “Using the instance manager to control subforms at run time” on page 111
The scripting examples demonstrate quick and simple techniques that you can apply to your own work.
For more examples and ideas, visit the LiveCycle ES2 Developer Center at www.adobe.com/devnet/livecycle.

Changing the background colors of fields, fillable areas, and subforms

This example demonstrates how to change the background color of subforms, fields, and fillable areas on a form in response to form filler
interaction at run time.
 LIVECYCLE DESIGNER ES2 90
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

In this example, clicking a button changes the background color of an associated object.

Note: To manipulate the background color of objects at run time, you must save your form as an Acrobat Dynamic XML Form file.
To see this scripting example and others, visit the LiveCycle ES2 Developer Center at www.adobe.com/devnet/livecycle.

Scripting the subform and text field background colors

You set the subform and the text field background colors by using the fillColor method. For example, the following line is the script for
the subform:
Subform1.fillColor = "17,136,255";

The following lines make up the script for the background color of the text fields:
Subform1.Name.fillColor = "102,179,255";
Subform1.Address.fillColor = "102,179,255";
Subform1.City.fillColor = "102,179,255";
Subform1.State.fillColor = "102,179,255";
Subform1.ZipCode.fillColor = "102,179,255";
Subform1.Country.fillColor = "102,179,255";

Scripting the fillable area background color

When setting the background color or the fillable area for each text field, your scripts must access properties that require a reference syntax
expression that includes the number sign (#). Because JavaScript does not interpret the number sign (#) properly in reference syntax expres-
sions, the script uses the resolveNode method to resolve the expression.
xfa.resolveNode("Subform1.Name.ui.#textEdit.border.fill.color").value = "153,204,255";
xfa.resolveNode("Subform1.Address.ui.#textEdit.border.fill.color").value = "153,204,255";
xfa.resolveNode("Subform1.City.ui.#textEdit.border.fill.color").value = "153,204,255";
xfa.resolveNode("Subform1.State.ui.#textEdit.border.fill.color").value = "153,204,255";
xfa.resolveNode("Subform1.ZipCode.ui.#textEdit.border.fill.color").value = "153,204,255";
xfa.resolveNode("Subform1.Country.ui.#textEdit.border.fill.color").value = "153,204,255";
 LIVECYCLE DESIGNER ES2 91
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Scripting the Clear All button

The script for the Clear All button uses the remerge method to remerge the form design and form data. In this case, the method effectively
restores the fields, fillable areas, and subforms to their original state.
xfa.form.remerge();

Hiding and showing objects

This example demonstrates how to hide buttons when printing a form, as well as how to hide and show objects by changing the presence
values at run time.
Note: You can also use the Action Builder dialog box on the Tools menu to hide and show objects in forms that have a flowable layout, without
writing scripts.
In this example, all form objects are showing in the form.
 LIVECYCLE DESIGNER ES2 92
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

The form filler can use the drop-down lists in the Presence Values area to show or hide objects. In the following diagram, the Address field
is hidden and the form layout has adjusted accordingly. The Print Form button is also invisible.

Note: To hide and show objects at run time, you must save your form as an Acrobat Dynamic PDF Form file.
To see this scripting example and others, visit the LiveCycle ES2 Developer Center www.adobe.com/devnet/livecycle.

Scripting the presence values for subforms

The script for the subform presence values uses a switch statement to handle the three presence options that a form filler can apply to the
subform object:
switch(xfa.event.newText) {
case 'Invisible':
Subform1.presence = "invisible";
break;
case 'Hidden (Exclude from Layout)':
Subform1.presence = "hidden";
break;
default:
Subform1.presence = "visible";
break;
}

Scripting the presence values for text fields

The script for the text fields presence values requires two variables. The first variable stores the number of objects contained in Subform1:
var nSubLength = Subform1.nodes.length;
 LIVECYCLE DESIGNER ES2 93
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

The second variable stores the name of the text field that the form filler selects in the Text Fields drop-down list:
var sSelectField = fieldList.rawValue;

The following script uses the replace method to remove all of the spaces from the name of the field stored in the sSelectField variable,
which allows the value of the drop-down list to match the name of the object in the Hierarchy palette:
sSelectField = sSelectField.replace(' ', '');

This script uses a For loop to cycle through all of the objects contained in Subform1:
for (var nCount = 0; nCount < nSubLength; nCount++) {

If the current object in Subform1 is of type field and the current object has the same name as the object that the form filler selected, the
following switch cases are performed:
if ((Subform1.nodes.item(nCount).className == "field") & (Subform1.nodes.item(nCount).name == sSelectField)) {

The following script uses a switch statement to handle the three presence values that a form filler can apply to text field objects:
switch(xfa.event.newText) {
case 'Invisible':
Subform1.nodes.item(nCount).presence = "invisible";
break;
case 'Hidden (Exclude from Layout)':
Subform1.nodes.item(nCount).presence = "hidden";
break;
default:
Subform1.nodes.item(nCount).presence = "visible";
break;
}
}
}

Scripting the presence values for buttons

The script for the buttons presence values requires two variables. This variable stores the number of objects contained in Subform1:
var nSubLength = Subform1.nodes.length;

This variable stores the name of the button that the form filler selects in the Buttons drop-down list:
var sSelectButton = buttonList.rawValue;

The following script uses the replace method to remove all of the spaces from the name of the button stored in the sSelectField variable,
which allows the value of the drop-down list to match the name of the object in the Hierarchy palette:
sSelectButton = sSelecButton.replace(/\s/g, '');

This script uses a For loop to cycle through all of the objects contained in Subform1:
for (var nCount = 0; nCount < nSubLength; nCount++) {

If the current object in Subform1 is of type field and the current object has the same name as the object that the form filler selected,
perform the following switch cases:
if ((Subform1.nodes.item(nCount).className == "field") &
Subform1.nodes.item(nCount).name == sSelectButton)) {

This script uses a switch statement to handle the five presence values that a form filler can apply to button objects.
Note: The relevant property indicates whether an object should appear when the form is printed.
switch(xfa.event.newText) {
case 'Invisible':
Subform1.nodes.item(nCount).presence = "invisible";
 LIVECYCLE DESIGNER ES2 94
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

break;
case 'Hidden (Exclude from Layout)':
Subform1.nodes.item(nCount).presence = "hidden";
break;
case 'Visible (but Don\'t Print)':
Subform1.nodes.item(nCount).presence = "visible";
Subform1.nodes.item(nCount).relevant = "-print";
break;
case 'Invisible (but Print Anyway)':
Subform1.nodes.item(nCount).presence = "invisible";
Subform1.nodes.item(nCount).relevant = "+print";
break;
default:
Subform1.nodes.item(nCount).presence = "visible";
break;
}
}
}

Scripting for resetting the drop-down lists

Use the resetData method to reset all of the drop-down lists to their default values:
xfa.host.resetData();

Use the remerge method to remerge the form design and form data. In this case, the method effectively returns the objects in the Form
Objects area to their original states:
xfa.form.remerge();

Excluding an object from the tabbing order

This example demonstrates how to exclude an object from the default tabbing sequence. In this example, a user would begin in TextField1
and use the Tab button to navigate to TextField2 and then to TextField3. However, the drop-down list object, DropDownList1, is configured
to display when the user’s cursor enters TextField2.
 LIVECYCLE DESIGNER ES2 95
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

In this case, by default, the user’s experience would be to move sequentially in the following order:

To exclude DropDownList1 from the tabbing sequence, you would add the following scripts to the TextField2 object:

Event Script

enter // This conditional statement displays DropDownList3 to the user

// and sets the focus of the client application to TextField2.
if (DropDownList3.presence != "visible") {
DropDownList3.presence = "visible";
xfa.host.setFocus(this);
}

exit // This conditional statement tests to see if the user is

// pressing the Shift key while pressing the Tab key. If Shift is
// held down, then the client application focus returns to
// TextField1, otherwise the focus is set to TextField3. The
// experience for the user is that DropDownList3 is not a
// part of the tabbing order.
var isShiftDown = xfa.event.shift;
if (isShiftDown) {
xfa.host.setFocus(TextField1);
} else {
xfa.host.setFocus(textField3);
}
 LIVECYCLE DESIGNER ES2 96
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Changing the visual properties of an object on the client

The example demonstrates how to manipulate the visual properties of an object; in this case, a text field. For example, selecting the Make
the Field Wider check box expands the fillable area of the text field to four inches.

Note: To alter the visual properties of objects on the client, you must save your form as an Acrobat Dynamic PDF Form file.
In this example, the check boxes do not have unique object names; therefore, Designer ES2 assigns an instance value to reference the object.
The check box script uses an if-else statement to give the effect of selecting and deselecting.
To see this scripting example and others, visit the LiveCycle ES2 Developer Center www.adobe.com/devnet/livecycle.

Scripting for the Move the Field check box

When the check box is selected, the field is moved according to the x and y settings. When the check box is deselected, the field is returned
to its original location.
if (CheckBox1.rawValue == true) {
TextField.x = "3.0in";
TextField.y = "3.5in";
}
else {
TextField.x = "1in";
TextField.y = "3in";
}
 LIVECYCLE DESIGNER ES2 97
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Scripting for the Make the Field Wider check box

When the check box is selected, the field changes to 4 inches. When the check box is deselected, the field width changes to 2.5 inches.
if (CheckBox2.rawValue == true)
TextField.w = "4in";
else
TextField.w = "2.5in";

Scripting for the Make the Field Taller check box

When the check box is selected, the field height changes to 1.5 inches. When the check box is deselected, the field height changes to .5 inches.
if (CheckBox3.rawValue == true)
TextField.h = "1.5in";
else
TextField.h = "0.5in";

Scripting for the Change the Border Color of the Object check box
When the check box is selected, the field border changes to red. When the check box deselected, the field border changes to white.
if (CheckBox4.rawValue == true)
TextField.border.edge.color.value = "255,0,0";
else
TextField.border.edge.color.value = "255,255,255";

Scripting for the Change the Fill Color of the Fillable Area check box
When the check box is selected, the fillable area of the text field changes to green. When the check box is deselected, the fillable area of the
text field changes to white.
if (CheckBox5.rawValue == true) {
xfa.resolveNode("TextField.ui.#textEdit.border.fill.color").value = "0,255,0";
}
else {
xfa.resolveNode("TextField.ui.#textEdit.border.fill.color").value = "255,255,255";
}

Scripting for the Expand to Fit the Width of the Value check box
When the check box is selected, the fillable area of the text field adjusts to accommodate the value. When the check box is deselected, the
fillable area of the text field does not adjust.
if (CheckBox6.rawValue == true)
TextField.minW = "0.25in";
else
TextField.maxW = "2.5in";

Scripting for the Make the Field Disappear check box

When the check box is selected, the field is hidden. When the check box is deselected, the field is visible.
if (CheckBox7.rawValue == true)
TextField.presence = "hidden";
else
TextField.presence = "visible";

Scripting for the Change the Font of the Value check box
When the check box is selected, the font of the value changes to Courier New. When the check box is deselected, the font of the value changes
to Myriad Pro.
if (CheckBox8.rawValue == true)
 LIVECYCLE DESIGNER ES2 98
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

TextField.font.typeface = "Courier New";

else
TextField.font.typeface = "Myriad Pro";

Scripting for the Change the Size of the Font check box
When the check box is selected, the font size changes to 14 pt. When the check box is deselected, the font size changes to 10 pt.
if (CheckBox9.rawValue == true)
TextField.font.size = "14pt";
else
TextField.font.size = "10pt";

Scripting for the Align Text Field Value Vertically check box
When the check box is selected, the text field value is aligned to the top. When the check box is deselected, the text field value is aligned to
the middle.
if (CheckBox10.rawValue == true)
TextField.para.vAlign = "top";
else
TextField.para.vAlign = "middle";

Scripting for the Align Text Field Value Horizontally check box
When the check box is selected, the text field value is aligned to the center. When the check box is deselected, the text field value is aligned
to the left.
if (CheckBox11.rawValue == true)
TextField.para.hAlign = "center";
else
TextField.para.hAlign = "left";

Scripting for the Display a Set Value check box

When the check box is selected, the value that is defined by using a script appears in the text field. When the check box is deselected, the
default value (which is also defined by using a script) appears in the text field.
if (CheckBox12.rawValue == true)
TextField.rawValue = "This is a value set using a script.";
else
TextField.rawValue = "This is a default value.";

Scripting for the Change the Caption Text check box

When the check box is selected, the alternate caption text that is defined by using a script appears as the caption. When the check box is
deselected, the default caption (which is also defined by using a script) appears in the text field.
if (CheckBox13.rawValue == true)
xfa.resolveNode("TextField.caption.value.#text").value = "Alternate Caption:";
else
xfa.resolveNode("TextField.caption.value.#text").value = "Caption:";

Scripting for the Change Field Border from 3D to Solid check box
When the check box is selected, the field border changes to a solid box. When the check box is deselected, the field border changes to 3D.
if (CheckBox14.rawValue == true)
xfa.resolveNode("TextField.ui.#textEdit.border.edge").stroke = "solid";
else
xfa.resolveNode("TextField.ui.#textEdit.border.edge").stroke = "lowered";
 LIVECYCLE DESIGNER ES2 99
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Scripting for the Clear All Check Boxes button

Use the resetData method to reset all of the check boxes to their default value (Off).
xfa.host.resetData();

Use the remerge method to remerge the form design and form data. In this case, the method effectively returns the text field to its original
state.
xfa.form.remerge();

Getting the current or previous value of a drop-down list

This example demonstrates how to obtain the current value of a drop-down list as well as the different ways to access the previous value of
a drop-down list on a form. In addition to the actual scripts that set the current and previous values, it is important to note that the scripts
are located on the change event for the drop-down list.
In the following example, when a form filler selects a value from the drop-down list, the selected value appears in the Current Value field.
Then, when the form filler selects another value from the drop-down list, the new value appears in the Current Value List and the previous
value appears in the Previous Value 1 field.

Note: Each of the methods for obtaining the previous value of a drop-down list uses a different script. The Previous Value 1 text field is populated
by a direct reference to the rawValue property of the drop-down list, whereas the Previous Value 2 text field is populated using the prevText
property. For consistent results, it is recommended that you access the previous value by using the prevText property.
To see this scripting example and others, visit the LiveCycle ES2 Developer Center at www.adobe.com/devnet/livecycle.

Scripting for populating the Current Value text field

Populate the value of the Current Value text field by using the newText property:
CurrentValue.rawValue = xfa.event.newText;

Scripting for populating the Previous Value 1 text field

Populate the value of the Previous Value 1 text field by referencing the rawValue of the drop-down list:
PreviousValue1.rawValue = DropDownList.rawValue;
 LIVECYCLE DESIGNER ES2 100
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Scripting for populating the Previous Value 2 text field

Populate the value of the Previous Value 2 text field by using the prevText property:
PreviousValue2.rawValue = xfa.event.prevText;

Preserving rich text formatting when copying field values

This example demonstrates how to maintain rich text formatting of field data when copying values between fields.

TextField1 and TextField2 are configured to Allow Multiple Lines and display rich text formatting.
The Copy Rich Text button copies the value of TextField1, including rich text formatting, and pastes it in TextField2.

Scripting for the Copy Rich Text button

Rich text field values are stored in XML format within a child object of the field that contains the value. The following script, located on the
click event of the Copy Rich Text button, uses the saveXML method to store the XML definition of the rich text value. Subsequently, the
XML data is loaded into the corresponding child object of TextField2.
var richText = TextField1.value.exData.saveXML();
TextField2.value.exData.loadXML(richText,1,1);

In this example, the rich text value is set to overwrite the existing value of TextField2. Adjusting the script to the following would append
the rich text data to the current value of TextField2:
var richText = TextField1.value.exData.saveXML();
TextField2.value.exData.loadXML(richText,1,0);

Adjusting the height of a field at run time

The example demonstrates how to expand a field to match the height of the content in another field.
In this example, when the form filler types multiple lines in TextField1 and then clicks the Expand button, the height of TextField2 increases
to match the height of TextField1.
 LIVECYCLE DESIGNER ES2 101
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

To see this scripting example and others, visit the LiveCycle ES2 Developer Center at www.adobe.com/devnet/livecycle.

Scripting for the Expand button

The following script is for the Expand button:
var newHeight = xfa.layout.h(TextField1, "in");
TextField2.h = newHeight + "in";

Setting a field as required at run time

This example demonstrates how to make a field required at run time.
In this example, when the Set as Required button is clicked, if the form filler attempts to submit a form without typing some text in
TextField1, an error message appears.

To see this scripting example and others, visit the LiveCycle ES2 Developer Center www.adobe.com/devnet/livecycle.

Scripting for the Set as Required button

The following script is for the Set as Required button:
TextField1.validate.nullTest = "error";

You can also use one of these two scripts:

TextField1.mandatory = "error"
TextField1.mandatoryMessage = "this field is mandatory!"

Calculating the field sums

This example demonstrates how to calculate the sums of fields located at different levels of the form hierarchy when the form filler opens
the form in a client application, such as Acrobat Professional, Adobe Reader, or HTML client.

To see this scripting example and others, visit the LiveCycle ES2 Developer Center at www.adobe.com/devnet/livecycle.
 LIVECYCLE DESIGNER ES2 102
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Scripting for calculating the sum of repeating fields in a form

To calculate the sum of repeating fields in a form, you add a calculate event to the Sum field:
var fields = xfa.resolveNodes("NumericField1[*]");

var total = 0;
for (var i=0; i <= fields.length-1; i++) {
total = total + fields.item(i).rawValue;
}

this.rawValue = total;

Scripting for calculating the sum of repeating fields

Similarly, to calculate the sum of repeating fields, you add a calculate event to the Sum field:
var fields = xfa.resolveNodes("detail[*].NumericField1");

var total = 0;
for (var i=0; i <= fields.length-1; i++) {
total = total + fields.item(i).rawValue;
}

this.rawValue = total;

Scripting to calculate the sum of the fields on the page

To calculate the sum of the fields on the page, you add a calculate event to the Sum field:
var fields = xfa.layout.pageContent(0 , "field", 0);

var total = 0;
for (var i=0; i <= fields.length-1; i++) {
if (fields.item(i).name == "NumericField1") {
total = total + fields.item(i).rawValue;
}
}

this.rawValue = total;

Highlighting fields in response to form filler interaction

This example demonstrates how to highlight the current field that a form filler is working with, highlight fields that a form filler is required
to fill, and use message boxes to provide feedback to the form filler.
 LIVECYCLE DESIGNER ES2 103
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

In this example, an asterisk (*) appears to the right of the required fields. When a field is selected, the field border changes to blue. If the
form filler clicks the Verify Data button without having filled the required fields, a message appears and the field changes to red. If all the
required fields are filled, a confirmation message appears when the form filler clicks the Verify Data button.

To see this scripting example and others, visit the LiveCycle ES2 Developer Center at www.adobe.com/devnet/livecycle.

Scripting for adding a blue border around a selected field

To add the blue border around the selected field, add the following scripts to each text field:
For example, add an enter event to the Name field:
Name.border.edge.color.value = "0,0,255";

For example, add an exit event to the Name field:

Name.border.edge.color.value = "255,255,255";

For example, add a mouseEnter event to the Name field:

Name.border.edge.color.value = "0,0,255";

For example, add a mouseExit event to the Name field:

Name.border.edge.color.value = "255,255,255";

Scripting for the Verify Data button

The following script, which is created for the Verify Data button, performs a series of checks to verify that the required fields contain data.
In this case, each field is individually checked to verify that the value of the field is non-null or an empty string. If the value of the field is
null or an empty string, an alert message appears indicating that data must be input into the field and the background color of the fillable
area is changed to red.
Use this variable to indicate whether a field does not contain data:
 LIVECYCLE DESIGNER ES2 104
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

var iVar = 0;

if ((Name.rawValue == null) || (Name.rawValue == "")) {

xfa.host.messageBox("Please enter a value in the Name field.");

This script changes the color of the fillable area of the text field:
xfa.resolveNode("Name.ui.#textEdit.border.edge").stroke = "solid";
xfa.resolveNode("Name.ui.#textEdit.border.fill.color").value = "255,100,50";

// Set the variable to indicate that this field does not contain data.
iVar = 1;
}
else {
// Reset the fillable area of the text field.
xfa.resolveNode("Name.ui.#textEdit.border.edge").stroke = "lowered";
xfa.resolveNode("Name.ui.#textEdit.border.fill.color").value = "255,255,255";
}

if ((Address.rawValue == null) || (Address.rawValue == "")) {

xfa.host.messageBox("Please enter a value in the Address field.");

This script changes the color of the fillable area of the text field:
xfa.resolveNode("Address.ui.#textEdit.border.edge").stroke = "solid";
xfa.resolveNode("Address.ui.#textEdit.border.fill.color").value = "255,100,50";

This script sets the variable to indicate that this field does not contain data:
iVar = 1;
}
else {

This script resets the fillable area of the text field:

xfa.resolveNode("Address.ui.#textEdit.border.edge").stroke = "lowered";
xfa.resolveNode("Address.ui.#textEdit.border.fill.color").value = "255,255,255";
}

if ((City.rawValue == null) || (City.rawValue == "")) {

xfa.host.messageBox("Please enter a value in the City field.");

This script changes the color of the fillable area of the text field:
xfa.resolveNode("City.ui.#textEdit.border.edge").stroke = "solid";
xfa.resolveNode("City.ui.#textEdit.border.fill.color").value = "255,100,50";

This script sets the variable to indicate that this field does not contain data:
iVar = 1;
}
else {

This script resets the fillable area of the text field:

xfa.resolveNode("City.ui.#textEdit.border.edge").stroke = "lowered";
xfa.resolveNode("City.ui.#textEdit.border.fill.color").value = "255,255,255";
}

if ((State.rawValue == null) || (State.rawValue == "")) {

xfa.host.messageBox("Please enter a value in the State field.");

This script changes the color of the fillable area of the text field:
xfa.resolveNode("State.ui.#textEdit.border.edge").stroke = "solid";
 LIVECYCLE DESIGNER ES2 105
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

xfa.resolveNode("State.ui.#textEdit.border.fill.color").value = "255,100,50";

This script sets the variable to indicate that this field does not contain data:
iVar = 1;
}
else {

This script resets the fillable area of the text field:

xfa.resolveNode("State.ui.#textEdit.border.edge").stroke = "lowered";
xfa.resolveNode("State.ui.#textEdit.border.fill.color").value = "255,255,255";
}

if ((ZipCode.rawValue == null) || (ZipCode.rawValue == "")) {

xfa.host.messageBox("Please enter a value in the Zip Code field.");

This script changes the color of the fillable area of the text field:
xfa.resolveNode("ZipCode.ui.#textEdit.border.edge").stroke = "solid";
xfa.resolveNode("ZipCode.ui.#textEdit.border.fill.color").value = "255,100,50";

This script sets the variable to indicate that this field does not contain data:
iVar = 1;
}
else {

This script resets the fillable area of the text field:

xfa.resolveNode("ZipCode.ui.#textEdit.border.edge").stroke = "lowered";
xfa.resolveNode("ZipCode.ui.#textEdit.border.fill.color").value = "255,255,255";
}

if ((Country.rawValue == null) || (Country.rawValue == "")) {

xfa.host.messageBox("Please enter a value in the Country field.");

This script changes the color of the fillable area of the text field:
xfa.resolveNode("Country.ui.#textEdit.border.edge").stroke = "solid";
xfa.resolveNode("Country.ui.#textEdit.border.fill.color").value = "255,100,50";

This script sets the variable to indicate that this field does not contain data.
iVar = 1;
}
else {

This script resets the fillable area of the text field.

xfa.resolveNode("Country.ui.#textEdit.border.edge").stroke = "lowered";
xfa.resolveNode("Country.ui.#textEdit.border.fill.color").value = "255,255,255";
}

If all of the required fields contain data, the iVar variable is set to zero, and a confirmation message appears:
if (iVar == 0) {
xfa.host.messageBox("Thank you for inputting your information.");
}

Resetting the values of the current subform

This example demonstrates how to reset the values of a specific set of fields, not the whole form. To do this, reset only the fields in the
required subform object.
 LIVECYCLE DESIGNER ES2 106
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

In this example, the form filler can click the Clear button to reset the field values.

To see this scripting example and others, visit the LiveCycle ES2 Developer Center www.adobe.com/devnet/livecycle.

Scripting for the values that appear in the left column

Type this script for the values appearing in the left column:
this.rawValue = this.parent.index + 1;

To reset the default values add a click event to the Clear button. You need a dynamic reference syntax expression because the detail is a
repeating subform and must be reflected in the reference syntax expression. In this situation, it is easier to build the resetData parameters
separately.
var f1 = this.parent.somExpression + ".TextField2" + ",";
var f2 = f1 + this.parent.somExpression + ".DropDownList1" + ",";
var f3 = f2 + this.parent.somExpression + ".NumericField1";

// ...and pass the variable as a parameter.

xfa.host.resetData(f3);

Changing the presence of a form design object

Designer ES2 provides the following presence settings for the different objects on a form through various tabs in the Object palette. The
Invisible and Hidden (Exclude from Layout) settings are unavailable for groups, content areas, master pages, page set, and subform set
objects.
Note: To change the presence setting of an object by using scripts, you must change the value of two underlying XML Form Object Model
properties: presence and relevant.
The following table lists the presence settings and the corresponding reference syntax.

Presence setting Reference syntax

Visible FormCalc

ObjectName.presence = "visible"

JavaScript

ObjectName.presence = "visible";

Visible (Screen Only) FormCalc

ObjectName.presence = "visible"
ObjectName.relevant = "-print"

JavaScript

ObjectName.presence = "visible";
ObjectName.relevant = "-print";
 LIVECYCLE DESIGNER ES2 107
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Presence setting Reference syntax

Visible (Print Only) FormCalc

ObjectName.presence = "visible"
ObjectName.relevant = "+print"

JavaScript

ObjectName.presence = "visible";
ObjectName.relevant = "+print";

Invisible FormCalc

ObjectName.presence = "invisible"

JavaScript

ObjectName.presence = "invisible";

Hidden (Exclude from Layout) FormCalc

ObjectName.presence = "hidden"

JavaScript

ObjectName.presence = "hidden";

One-sided Printing Only FormCalc

ObjectName.presence = "simplex"

JavaScript

ObjectName.presence = "simplex";

Two-sided Printing Only FormCalc

ObjectName.presence = "duplex"

JavaScript

ObjectName.presence = "duplex";

Using the properties of the instance manager to control subforms

This example demonstrates how to use the properties of the instance manager (which is part of the XML Form Object Model) to retrieve
information about subforms at run time.
 LIVECYCLE DESIGNER ES2 108
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

In the following form, the four buttons provide information about Subform1 by using the instance manger’s scripting properties. For
example, when the form filler clicks the Max button, a message describing the allowed maximum number of supported Subform1 instances
appears.

Scripting for the message box to output the value of the count property
The following script uses the messageBox method to output the value of the count property:
xfa.host.messageBox("The current number of Subform1 instances on the
form is:" + properties.Subform1.instanceManager.count, "Instance Manager
Properties",3);

You can also write this script by using the underscore (_) notation to reference the count property of the instance manager, as shown here:
xfa.host.messageBox("The current number of Subform1 instances on the form
is: " + properties._Subform1.count, "Instance Manager Properties", 3);

The underscore (_) notation is especially important if no subform instances currently exist on the form.

Scripting for the message box to output the value of the max property
The following script uses the messageBox method to output the value of the max property:
xfa.host.messageBox("The maximum number of instances allowed for Subform1
is: " + properties.Subform1.instanceManager.max, "Instance Manager
Properties", 3);

You can also write this script by using the underscore (_) notation to reference the max property of the instance manager, as shown here:
xfa.host.messageBox("The maximum number of instances allowed for Subform1
is: " + properties._Subform1.max, "Instance Manager Properties", 3);

Scripting for the message box to output the value of the min property
The following script uses the messageBox method to output the value of the min property:
xfa.host.messageBox("The minimum number of instances allowed for Subform1
is: " + properties.Subform1.instanceManager.min, "Instance Manager
Properties", 3);

You can also write this script by using the underscore (_) notation to reference the min property of the instance manager, as shown here:
 LIVECYCLE DESIGNER ES2 109
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

xfa.host.messageBox("The minimum number of instances allowed for Subform1

is: " + properties._Subform1.min, "Instance Manager Properties", 3);

Scripting for the message box to output the name of the subform property
The following script uses the messageBox method to output the name of the subform property:
xfa.host.messageBox("The name of the subform using the instance manager name
property is: " + properties.Subform1.instanceManager.name +
".\n\nNote: This value is different than the value returned by the name
property for the Subform1 object." , "Instance Manager Properties", 3);

You can also write this script by using the underscore (_) notation to reference the name property of the instance manager, as shown here:
xfa.host.messageBox("The name of the subform using the instance manager name
property is: " + properties._Subform1.name +
".\n\nNote: This value is different than the value returned by the name
property for the Subform1 object." , "Instance Manager Properties", 3);

Using the methods of the instance manager to control subforms

This example demonstrates how to use the methods of the instance manager (which is part of the XML Form Object Model) to perform
operations on subform objects at run time. For example, you can add remove instances of a particular subform, table, or table row.
In the following form, the form filler uses the four buttons to use the various instance manager scripting methods. For example, when the
form filler clicks the Add button a new Subform2 instance is added to the form.

Note: The Move button reorders the first two Subform2 instances, and the Set button displays the maximum number of Subform2 instances. In
both cases, you may need to add or remove subforms, or make changes to the data in the text fields to see the changes applied to the Subform2
instances.

Scripting to determine whether you added the maximum number of subforms to a form
The following script determines whether the supported maximum number of Subform2 instances exist on the form. If the maximum
number exists, the script displays a message. Otherwise, a new Subform2 instance is added to the form.
if (methods.Subform2.instanceManager.count ==
methods.Subform2.instanceManager.max) {
xfa.host.messageBox("You have reached the maximum number of items allowed.",
"Instance Manager Methods", 1);
}
else {
methods.Subform2.instanceManager.addInstance(1);
xfa.form.recalculate(1);
 LIVECYCLE DESIGNER ES2 110
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

}
You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
if (methods._Subform2.count == methods._Subform1.max) {
xfa.host.messageBox("You have reached the maximum number of items
allowed.", "Instance Manager Methods", 1);
}
else {
methods._Subform2.addInstance(1);
xfa.form.recalculate(1);
}

Scripting to determine whether there are more subforms to remove on the form
The following script determines whether any Subform2 instances exist on the form. If none exist, the script displays a message indicating
that no instances exist. If instances do exist, the script removes the first instance from the form.
if (methods.Subform2.instanceManager.count == 0) {
xfa.host.messageBox("There are no subform instances to remove.",
"Instance Manager Methods", 1);
}
else {
methods.Subform2.instanceManager.removeInstance(0);
xfa.form.recalculate(1);
}

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
if (methods._Subform2.count == 0) {
xfa.host.messageBox("There are no subform instances to remove.",
"Instance Manager Methods", 1);
}
else {
methods._Subform2.removeInstance(0);
xfa.form.recalculate(1);
}

Scripting to force four subform instances to appear on the form

The following script forces four Subform2 instances to appear on the form regardless of how many instances currently exist:
methods.Subform2.instanceManager.setInstances(4);

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
methods._Subform2.setInstances(4);

Scripting to force the first and second subforms to switch locations on the form
The following script forces the first and second Subform2 instances to switch locations on the form.
methods.Subform2.instanceManager.moveInstance(0,1);

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here.
methods._Subform2.moveInstance(0,1);
 LIVECYCLE DESIGNER ES2 111
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Using the instance manager to control subforms at run time

This example demonstrates how to use properties and methods of the instance manager to retrieve information about subforms and perform
operations on subform objects at run time.
In this example, the form filler uses the buttons to perform various actions using instances of Subform3. For example, when the form filler
clicks the Add Row Below button a new Subform3 instance is added below the current instance.
Note: You may need to add or remove subforms, or make changes to the data in the text field, to see the changes applied to the instances of
Subform3.

Note: If no instances of a particular subform exist on your form, you must use the underscore (_) notation provided with each example below.
For more information about using the underscore (_) notation, see Designer ES2 Help.

Scripting the Add a New Subform button

The following script determines whether the supported maximum number of Subform3 instances exist on the form. If the maximum
number exist, the script displays a message. Otherwise, a new Subform3 instance is added to the form.
if (advanced.Subform3.instanceManager.count ==
advanced.Subform3.instanceManager.max) {
xfa.host.messageBox("You have reached the maximum number of items
allowed.","Combining Instance Manager Concepts", 1);
}
else {
advanced.Subform3.instanceManager.addInstance(1);
xfa.form.recalculate(1);
}

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
if (advanced._Subform3.count == advanced._Subform3.max) {
xfa.host.messageBox("You have reached the maximum number of items
allowed.", "Combining Instance Manager Concepts", 1);
}
else {
advanced._Subform3.addInstance(1);
xfa.form.recalculate(1);
}
 LIVECYCLE DESIGNER ES2 112
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Scripting the Remove a Subform button

The following script determines whether any Subform3 instances exist on the form. If none exist, the script displays a message indicating
that no instances exist. If instances exist, the script removes the first instance from the form.
if (advanced.Subform3.instanceManager.count == 0) {
xfa.host.messageBox("There are no subform instances to remove.",
"Combining Instance Manager Concepts", 1);
}
else {
advanced.Subform3.instanceManager.removeInstance(0);
}

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
if (advanced._Subform3.count == 0) {
xfa.host.messageBox("There are no subform instances to remove.",
"Combining Instance Manager Concepts", 1);
}
else {
advanced._Subform3.removeInstance(0);
}

Scripting the Add Instance Below button

The following if-else statement prevents the script from proceeding if the form currently contains the maximum number of Subform3
instances:
if (Subform3.instanceManager.count < Subform3.instanceManager.occur.max) {
//oNewInstance stores an instance of Subform3 created by the addInstance() method.
var oNewInstance = Subform3.instanceManager.addInstance(1);
//nIndexFrom and nIndexTo store the before and after index values to use with the moveInstance() method.
var nIndexFrom = oNewInstance.index;
var nIndexTo = Subform3.index + 1;

In this case, when the script references the value for nIndexFrom, the new instance of Subform3 is added to the form in the position specified
in the moveInstance method:
Subform3.instanceManager.moveInstance(nIndexFrom, nIndexTo);
}
else {
xfa.host.messageBox("You have reached the maximum number of items
allowed.", "Combining Instance Manager Concepts", 1);
}

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
if (_Subform3.count < _Subform3.occur.max) {
var oNewInstance = _Subform3.addInstance(1);
var nIndexFrom = oNewInstance.index;
var nIndexTo = Subform3.index + 1;
_Subform3.moveInstance(nIndexFrom, nIndexTo);
}
else {
xfa.host.messageBox("You have reached the maximum number of items allowed.", "Combining Instance Manager
Concepts", 1);
}
 LIVECYCLE DESIGNER ES2 113
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

Scripting the Delete This Instance button

The following if-else statement prevents the script from proceeding if the form currently contains the minimum number of Subform3
instances.
if (Subform3.instanceManager.count > Subform3.instanceManager.occur.min) {

This script uses the removeInstance method to remove an instance of Subform3.

Note: This script uses the value parent.parent.index to indicate the Subform3 instance to remove. The parent reference indicates the
container of the object using the reference. In this case, using the reference parent.index would indicate the untitled subform that contains the
Add Instance Below, Delete This Instance, Move Row Up, and Move Row Down buttons.
Subform3.instanceManager.removeInstance(parent.parent.index);
}
else {
xfa.host.messageBox("You have reached the minimum number of items
allowed.", "Combining Instance Manager Concepts", 1);
}

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
if (_Subform3.count > _Subform3.occur.min) {
Subform3.removeInstance(Subform3.index);
}
else {
xfa.host.messageBox("You have reached the minimum number of items allowed.",
"Combining Instance Manager Concepts", 1);
}

Scripting the Move Row Up button

The following if-else statement prevents the script from proceeding if the instance of Subform3 appears as the first instance in the list:
if (Subform3.index != 0) {
//nIndexFrom and nIndexTo store the before and after index values to use with the moveInstance method.
var nIndexFrom = Subform3.index;
var nIndexTo = Subform3.index - 1;
Subform3.instanceManager.moveInstance(nIndexFrom, nIndexTo);
}
else {
xfa.host.messageBox("The current item cannot be moved because it is the
first instance in the list.", "Combining Instance Manager Concepts", 1);
}

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
if (Subform3.index != 0) {
var nIndexFrom = Subform3.index;
var nIndexTo = Subform3.index - 1;
Subform3.moveInstance(nIndexFrom, nIndexTo);
}
else {
xfa.host.messageBox("The current item can't be moved since it already is the first instance in the
list.", "Combining Instance Manager Concepts", 1);
}

Scripting the Move Row Down button

This variable stores the index value of the instance of Subform3:
var nIndex = Subform3.index;
 LIVECYCLE DESIGNER ES2 114
Examples of Common Scripting Tasks LiveCycle Designer ES2 Scripting Basics

The following if-else statement prevents the script from proceeding if the instance of Subform3 appears as the last instance in the list:
if ((nIndex + 1) < Subform3.instanceManager.count) {
// nIndexFrom and nIndexTo store the before and after index values to use with the moveInstance() method.
var nIndexFrom = nIndex;
var nIndexTo = nIndex + 1;

Subform3.instanceManager.moveInstance(nIndexFrom, nIndexTo);
}
else {
xfa.host.messageBox("The current item cannot be moved because it is the last
instance in the list.", "Combining Instance Manager Concepts", 1);
}

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown
here:
var nIndex = Subform3.index;
if ((nIndex + 1) < Subform3.instanceManager.count) {
var nIndexFrom = nIndex;
var nIndexTo = nIndex + 1;
_Subform3.moveInstance(nIndexFrom, nIndexTo);
}
else {
xfa.host.messageBox("The current item can't be moved since it already is the
last instance in the list.", "Combining Instance Manager Concepts", 1);
}
 115

Index
A D postOpen (application event) 37
adding debugging postPrint (application event) 38
FormCalc functions to objects 47 about calculations and scripts 70 postSave (application event) 38
JavaScript scripts to objects 54 calculations and scripts 14, 22 postSign (application event) 39
script fragments 69 enabling the JavaScript Debugger 71 postSubmit (application event) 39
scripts to script objects 66 executing JavaScript scripts 71 preOpen (interactive event) 40
Adobe Acrobat using the messageBox method 70 prePrint (application event) 40
converting forms containing scripts 78 default preSave (application event) 41
JavaScript object model 78 processing application, setting 13 preSign (application event) 41
Adobe LiveCycle Designer ES scripting language, setting 13, 14 preSubmit (application event) 42
converting Acrobat forms to 78 defining text variables 55 processing events 24
scripting, moving from Acrobat 78 displaying scripting, viewing 20
application events 27 international characters 14 scripts associated with 20
Arabic characters, displaying 14 Script Editor 13 types of 24
array referencing 64 docClose event 30 validate (processing event) 42
docReady event 31 executing
B drop-down lists, value of, obtaining 99 events 24
basic calculations 48 scripts in JavaScript Console 71
built-in functions, FormCalc 47 E exit event 32
enter event 31 expressions, Acrobat-equivalent 75
C event model
calculate event 28 about 77 F
calculations scripting properties and methods 77 fields
about 9 event propagation 16 at run time, setting as required 101
about creating 16 events background color, changing 89
adding object reference syntax to 19 about 20, 24 height, adjusting at run time 100
attaching to objects 16 application events 27 highlighting 102
creating 17, 19 calculate (processing event) 28 sums, calculating 101
current object, referencing 61 change (interactive event) 29 form designs
debugging 14, 22, 70 click (interactive event) 30 object naming conventions 16
event model properties and methods 77 docClose (application event) 30 objects, changing presence of 106
referencing objects in 58, 60, 61 docReady (application event) 31 FormCalc
running 20, 21 enter (interactive event) 31 about 17, 47
testing 22 exit (interactive event) 32 basic calculations 48
variables 56 formready (processing event) 32 built-in functions 47
change event 29 full (interactive event) 33 function syntax 48
click event 30 indexChange (processing event) 33 functions 44
colors, background, changing 89 initialize (processing event) 34 functions, adding to objects 47
comparing FormCalc and JavaScript 44 interactive 25 reference syntax shortcuts 61
creating layoutready (processing event) 34 referencing objects 58, 60, 61
calculations and scripts 17, 19 mouseDown (interactive event) 35 formready event 32
script fragments 68 mouseEnter (interactive event) 36 forms, converting from Acrobat to LiveCycle
script objects 66 mouseExit (interactive events 36 Designer ES 78
mouseUp (interactive event) 37 fragments. See script fragments 68
full event 33
 INDEX 116

function syntax, FormCalc 48 N switching between single-line and multiline

naming view 13

H form design objects and variables 16 viewing scripts and events in 20

Hebrew characters, displaying 14 variables 55 script fragments
hiding objects 91 about script fragments 68
host application 75 O creating 68
Object palette inserting 69

I script fragment properties 68 properties in the Object palette 68

indexChange event 33 objects script objects 66, 67
initialize event 34 attaching calculations and scripts to 16 scripting
initiating events 24 calculation and script support 9 about examples 89
inserting making visible and invisible 106 against JavaScript object model in Acrobat 78
script fragments 69 naming conventions 16 event model properties and methods 77
instance manager referencing in calculations and scripts 58, 60, 61 moving from Adobe Acrobat 78
controlling subforms at run time 111 showing and hiding 91 scripting language, setting 13, 14, 17
methods, controlling subforms using 109 viewing attached scripts 20 scripting methods
properties, controlling subforms using 107 visual properties, changing 96 Acrobat-equivalent 75
interactive events 25 order of events 24 host scripting model 75
to control subforms 109

J P scripting properties
JavaScript postOpen event 37 Acrobat-equivalent 75
about 17, 50 postPrint event 38 host scripting model 75
to control subforms 107
scoping 51 postSave event 38
postSign event 39 scripts
adding scripts to objects 54
postSubmit event 39 about 9
enabling 71
preOpen event 40 about creating 16
functions 44
prePrint event 40 about debugging and testing 70
objects supported from Acrobat 79
preSave event 41 adding object reference syntax to 19
referencing objects 58, 60, 61
presence property 106 associating with events 20
using objects from Acrobat 78
preSign event 41 attached to objects, viewing 20
JavaScript Console
preSubmit event 42 attaching to objects 16
about 70
processing application, default 13 creating 17, 19
executing scripts in 71
processing events 24 current object, referencing 61
JavaScript Debugger
properties, visual, changing for objects 96 debugging 14, 22
about 70
executing in the JavaScript Console 71
enabling for LiveCycle Designer ES 71
R referencing objects in 58, 60, 61
prevent from disappearing 71
reference syntax running 20, 21
about 58 testing 22
L
adding to calculations and scripts 19 variables 56
layout
referencing object properties and values 58 sequence of events 24
eady event 34
referencing objects 60, 61 setting
shortcuts for FormCalc 61 default processing application 13
M
referencing script objects 67 default scripting language 13, 14
messageBox method 70
shortcuts, reference syntax 61
mouseDown event 35
S showing
mouseEnter event 36
Script Editor Script Editor 13
mouseExit event 36
about 11 scripting events and scripts 20
mouseUp event 37
displaying 13 showing objects 91
multiline view, Script Editor 11, 13
finding and replacing text in 18 simple expressions 48
 INDEX 117

single-line view, Script Editor 11, 13

strict scoping rules 51
subforms
background color, changing 89
controlling at run time 107, 109, 111
value, resetting 105

T
testing
calculations and scripts 22
JavaScript scripts 70
text variables
See also variables
defining 55
deleting 56
viewing definition 56
text, finding and replacing in XML Source tab and
Script Editor 18
Thai characters, displaying 14
triggering events 24

U
unnamed objects, referencing in calculations and
scripts 60

V
validate event 42
variables
See also text variables
about 55
in calculations and scripts 56
naming 55
naming conventions 16
Vietnamese characters, displaying 14

X
XML Form Object Model
about 58
instance manager 107
XML Source tab, finding and replacing text in 18