Designer Scripting Basics

Designer Scripting Basics
AEM 6.3 Forms
Legal notices
For legal notices, see http://help.adobe.com/en_US/legalnotices/index.html.
Last updated 26/4/17
Contents
About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Purpose and scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Additional information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Designer Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Scripting Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Scripting Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
User Forums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Scripting samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Scripting Using Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
How scripting works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Objects that support calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Understanding relationships between objects in the Object Library . . . . . . . . . . . . . . . 5
Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Configuring Designer for Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
To show the Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
To change from single-line to multiline view . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
To set the default scripting language for new forms . . . . . . . . . . . . . . . . . . . . . . . . 9
To set the default scripting language for the current form . . . . . . . . . . . . . . . . . . . . . 9
To set the default scripting language for the current form . . . . . . . . . . . . . . . . . . . . . 10
To set the default scripting language for a form template . . . . . . . . . . . . . . . . . . . . . 10
To set the default scripting language for a form template . . . . . . . . . . . . . . . . . . . . . 10
To set the default processing application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
To set the default processing application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
To change the default processing application for a form template . . . . . . . . . . . . . . . . 11
To change the default processing application for a form template . . . . . . . . . . . . . . . . 12
To display Arabic, Hebrew, Thai, and Vietnamese characters . . . . . . . . . . . . . . . . . . 12
i
Using the workspace to debug calculations and scripts . . . . . . . . . . . . . . . . . . . . . . 13
Creating Calculations and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Naming conventions for form design objects and variables . . . . . . . . . . . . . . . . . . . . 15
Choosing a scripting language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
To create a calculation or script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
To create a calculation or script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
To find text or other items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
To replace text or other items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
To use statement completion to create calculations and scripts . . . . . . . . . . . . . . . . . . 21
To insert object reference syntax automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Determining when to run your calculation or script . . . . . . . . . . . . . . . . . . . . . . . . 22
To view scripting events and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
To view a scripting event for a single object in the Script Editor . . . . . . . . . . . . . . 23
To view a scripting event for a container object and its children in the Script Editor . . 24
To view all scripting events for a single object in the Script Editor . . . . . . . . . . . . . 24
To view all scripting events for a container object and its children in the Script Editor . 24
To view all scripts for a single object in the Script Editor . . . . . . . . . . . . . . . . . . 25
To view all scripts for a container object and its children in the Script Editor . . . . . . 25
Determining where to run your calculation or script . . . . . . . . . . . . . . . . . . . . . . . 25
Testing and debugging calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
To check script syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Working around security restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Events . . . . . . . .
Types of events . .
Process events . . .
Interactive events .
Application events
calculate event . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
change event . . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
click event . . . . .
Description .
Type . . . . .
Support . . .
ii
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Version . . .
Example . . .
docClose event . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
docReady event . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
enter event . . . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
exit event . . . . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
form:ready event .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
full event . . . . . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
indexChange event
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
initialize event . .
Description .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 39
. 40
. 40
. 40
. 40
. 40
. 40
. 41
. 41
. 41
. 41
. 41
. 41
. 41
. 42
. 42
. 42
. 42
. 42
. 42
. 43
. 43
. 43
. 43
. 43
. 43
. 44
. 44
. 44
. 44
. 44
. 44
. 45
. 45
. 45
. 45
. 45
. 45
. 46
. 46
. 46
. 46
. 46
. 46
. 47
. 47
iii
Type . . . . .
Support . . .
Version . . .
Example . . .
layout:ready event
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
mouseDown event
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
mouseEnter event
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
mouseExit event .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
mouseUp event . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
postOpen event . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
postPrint event . .
Description .
Type . . . . .
Support . . .
Version . . .
Example . . .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 47
. 47
. 47
. 47
. 48
. 48
. 48
. 48
. 48
. 48
. 49
. 49
. 49
. 49
. 49
. 49
. 50
. 50
. 50
. 50
. 50
. 50
. 51
. 51
. 51
. 51
. 51
. 51
. 52
. 52
. 52
. 52
. 52
. 52
. 53
. 53
. 53
. 53
. 53
. 53
. 54
. 54
. 54
. 54
. 54
. 54
postSave event .
Description
Type . . . .
Support . .
Version . .
Example . .
postSign event .
Description
Type . . . .
Support . .
Version . .
Example . .
postSubmit event
Description
Type . . . .
Support . .
Version . .
Example . .
preOpen event .
Description
Type . . . .
Support . .
Version . .
Example . .
prePrint event . .
Description
Type . . . .
Support . .
Version . .
Example . .
preSave event . .
Description
Type . . . .
Support . .
Version . .
Example . .
preSign event . .
Description
Type . . . .
Support . .
Version . .
Example . .
preSubmit event
Description
Type . . . .
Support . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 55
. 55
. 55
. 55
. 55
. 55
. 56
. 56
. 56
. 56
. 56
. 56
. 57
. 57
. 57
. 57
. 57
. 57
. 58
. 58
. 58
. 58
. 58
. 58
. 59
. 59
. 59
. 59
. 59
. 59
. 60
. 60
. 60
. 60
. 60
. 60
. 61
. 61
. 61
. 61
. 61
. 61
. 62
. 62
. 62
. 62
v
Version . .
Example . .
validate event . .
Description
Type . . . .
Support . .
Version . .
Example . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 62
. 62
. 63
. 63
. 63
. 63
. 63
. 64
Scripting with FormCalc and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Using FormCalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Using built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
To attach a FormCalc function to an object . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Built-in function syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Creating basic calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
About basic calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Examples of basic calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Using JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Creating scripts using JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Enforcing strict scoping rules in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
What is scope in JavaScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
What is scope XML? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SOM expressions and scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Scoping and script objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Scoping and target version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
When to use scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
To enable strict scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
To attach a JavaScript script to an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Naming variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
To define a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
To define a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
To view a text variable definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
To view a text variable definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
To delete a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
To delete a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using variables in calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Referencing Objects in Calculations and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Referencing object properties and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Referencing unnamed and repeated objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Referencing the current object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
FormCalc reference syntax shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Current field or object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
vi
Data model root of xfa.datasets.data . . . . . . . .
Form object event . . . . . . . . . . . . . . . . . .
Form model root . . . . . . . . . . . . . . . . . . .
Host object . . . . . . . . . . . . . . . . . . . . . .
Layout model root . . . . . . . . . . . . . . . . . .
Collection of data record . . . . . . . . . . . . . .
Template model root . . . . . . . . . . . . . . . . .
Data model root of xfa.datasets . . . . . . . . . . .
Select all form objects . . . . . . . . . . . . . . . .
Search for objects that are part of a subcontainer .
Denote an unnamed object or specify a property .
Occurrence value of an object . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 93
. 93
. 93
. 94
. 94
. 95
. 95
. 95
. 96
. 96
. 97
. 98
Creating and Reusing JavaScript Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .
To create a script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To add script to a script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To reference JavaScript functions stored in a script object . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
100
100
101
101
101
102
Using Script Fragments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Script fragment properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fragment Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To create a script fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To insert a script fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To insert a script fragment from the Fragment Library palette: . . . . . . . . . . . . . .
To insert a script fragment from the Insert menu: . . . . . . . . . . . . . . . . . . . . .
103
103
103
103
104
104
104
105
Debugging Calculations and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designer Report palette warning and validation messages . . . . . . . . . . . . . . . . . . .
Providing debugging feedback using the messageBox method . . . . . . . . . . . . . . . . .
FormCalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output information into a text field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JavaScript Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JavaScript Debugger in Acrobat Professional . . . . . . . . . . . . . . . . . . . . . . . .
To enable the JavaScript Debugger for Designer . . . . . . . . . . . . . . . . . . . . . .
To prevent the JavaScript Debugger from disappearing in Designer . . . . . . . . . . .
Evaluating code using the JavaScript Console . . . . . . . . . . . . . . . . . . . . . . .
To evaluate a portion of a line of code . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To evaluate a single line of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To evaluate multiple lines of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To delete content that appear in the JavaScript Console . . . . . . . . . . . . . . . . . .
Providing debugging feedback to the JavaScript Console . . . . . . . . . . . . . . . . .
106
106
106
107
107
107
107
107
108
108
109
109
109
109
109
109
vii
Providing debugging feedback using the alert method .
Debugging tips . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample data . . . . . . . . . . . . . . . . . . . . . . . . .
Master pages . . . . . . . . . . . . . . . . . . . . . . . .
First page in a form . . . . . . . . . . . . . . . . . . . .
Incremental debugging . . . . . . . . . . . . . . . . . .
Hierarchy view . . . . . . . . . . . . . . . . . . . . . . .
Script error messages . . . . . . . . . . . . . . . . . . .
Syntax errors in FormCalc . . . . . . . . . . . . . . . .
Functions defined in a script object . . . . . . . . . . .
Web service calls . . . . . . . . . . . . . . . . . . . . . .
Long SOM expressions . . . . . . . . . . . . . . . . . .
Test SOM expressions . . . . . . . . . . . . . . . . . . .
Use script objects to debug form designs . . . . . . . .
Things to avoid when building forms . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
110
110
110
110
111
111
111
111
111
112
112
112
112
112
113
Working with a Host Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Host scripting model properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Comparing the host scripting model functionality . . . . . . . . . . . . . . . . . . . . . . . . 115
Working with the Event Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Event model properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Moving from Scripting in Acrobat to Designer . . . . . . . . . . . . . . . . . . . . . . . . .
Converting Acrobat forms that contain scripts . . . . . . . . . . . . . . . . . . . . . . . . . .
Using JavaScript objects from Acrobat in Designer . . . . . . . . . . . . . . . . . . . . . . .
JavaScript objects from Acrobat supported in Designer . . . . . . . . . . . . . . . . . . . . .
119
119
120
121
Examples of Common Scripting Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the background colors of fields, fillable areas, and subforms . . . . . . . . . . . .
Scripting the subform and text field background colors . . . . . . . . . . . . . . . . . .
Scripting the fillable area background color . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting the Clear All button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hiding and showing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting the presence values for subforms . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting the presence values for text fields . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting the presence values for buttons . . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting for resetting the drop-down lists . . . . . . . . . . . . . . . . . . . . . . . . .
Excluding an object from the tabbing order . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the visual properties of an object on the client . . . . . . . . . . . . . . . . . . . .
Scripting for the Move the Field check box . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting for the Make the Field Wider check box . . . . . . . . . . . . . . . . . . . . .
Scripting for the Make the Field Taller check box . . . . . . . . . . . . . . . . . . . . .
Scripting for the Change the Border Color of the Object check box . . . . . . . . . . .
139
139
139
140
140
140
142
143
143
144
145
146
146
147
147
147
viii
Scripting for the Change the Fill Color of the Fillable Area check box . . . . . . . . . . 147
Scripting for the Expand to Fit the Width of the Value check box . . . . . . . . . . . . 148
Scripting for the Make the Field Disappear check box . . . . . . . . . . . . . . . . . . . 148
Scripting for the Change the Font of the Value check box . . . . . . . . . . . . . . . . . 148
Scripting for the Change the Size of the Font check box . . . . . . . . . . . . . . . . . . 148
Scripting for the Align Text Field Value Vertically check box . . . . . . . . . . . . . . 149
Scripting for the Align Text Field Value Horizontally check box . . . . . . . . . . . . . 149
Scripting for the Display a Set Value check box . . . . . . . . . . . . . . . . . . . . . . 149
Scripting for the Change the Caption Text check box . . . . . . . . . . . . . . . . . . . 149
Scripting for the Change Field Border from 3D to Solid check box . . . . . . . . . . . 149
Scripting for the Clear All Check Boxes button . . . . . . . . . . . . . . . . . . . . . . . 150
Getting the current or previous value of a drop-down list . . . . . . . . . . . . . . . . . . . . 150
Scripting for populating the Current Value text field . . . . . . . . . . . . . . . . . . . 151
Scripting for populating the Previous Value 1 text field . . . . . . . . . . . . . . . . . . 151
Scripting for populating the Previous Value 2 text field . . . . . . . . . . . . . . . . . . 151
Preserving rich text formatting when copying field values . . . . . . . . . . . . . . . . . . . 151
Scripting for the Copy Rich Text button . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Adjusting the height of a field at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Scripting for the Expand button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Setting a field as required at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Scripting for the Set as Required button . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Calculating the field sums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Scripting for calculating the sum of repeating fields in a form . . . . . . . . . . . . . . 154
Scripting for calculating the sum of repeating fields . . . . . . . . . . . . . . . . . . . . 154
Scripting to calculate the sum of the fields on the page . . . . . . . . . . . . . . . . . . 154
Highlighting fields in response to form filler interaction . . . . . . . . . . . . . . . . . . . . 155
Scripting for adding a blue border around a selected field . . . . . . . . . . . . . . . . . 155
Scripting for the Verify Data button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Resetting the values of the current subform . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Scripting for the values that appear in the left column . . . . . . . . . . . . . . . . . . . 159
Changing the presence of a form design object . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Using the properties of the instance manager to control subforms . . . . . . . . . . . . . . . 160
Scripting for the message box to output the value of the count property . . . . . . . . 161
Scripting for the message box to output the value of the max property . . . . . . . . . 161
Scripting for the message box to output the value of the min property . . . . . . . . . 161
Scripting for the message box to output the name of the subform property . . . . . . . 162
Using the methods of the instance manager to control subforms . . . . . . . . . . . . . . . . 162
Scripting to determine whether you added the maximum number of subforms to a form
163
Scripting to determine whether there are more subforms to remove on the form . . . 163
Scripting to force four subform instances to appear on the form . . . . . . . . . . . . . 164
Scripting to force the first and second subforms to switch locations on the form . . . 164
Using the instance manager to control subforms at run time . . . . . . . . . . . . . . . . . . 164
Scripting the Add a New Subform button . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Scripting the Remove a Subform button . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Scripting the Add Instance Below button . . . . . . . . . . . . . . . . . . . . . . . . . . 166
ix
Scripting the Delete This Instance button . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Scripting the Move Row Up button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Scripting the Move Row Down button . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
x
About This Document
Welcome to Designer Scripting Basics. Scripting Basics provides you with an overview of how you
can use Designer calculations and scripts to develop and extend forms created in Designer.
You can use calculations and scripts to perform these types of 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
This document uses terms Adobe Experience Manager Forms, AEM Forms, AEM Forms on JEE,
and LiveCycle interchangeably.
NOTE:
Purpose and scope
Scripting Basics is intended for form authors and form developers interested in using calculations
and scripts to extend their Designer forms. 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.
Scripting Basics provides the following information:
•
An introduction to using Designer calculations and scripts to extend your forms
•
Easily understood, detailed information and examples of the Designer calculation and
scripting features
•
References to other resources where you can learn more about Designer scripting and related
technologies
After reading this guide, you should be equipped to start using Designer 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 successfully
complete your projects.
1
Additional information
Adobe has a wide variety of resources dedicated to Designer scripting focused at both the form
author and the form developer audiences.
Designer 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. You can access Designer Help from the Help menu , or online at Designer Help.
Scripting Basics
Provides an overview of creating calculations and scripts for use with Designer. This guide is
intended to help you create calculations and scripts using FormCalc and JavaScript.
Scripting Reference
The Scripting Reference is a detailed reference of the models, objects, properties, and methods that
you can use with Designer. This PDF is intended as reference material only; it is not intended to give
users information on how to create calculations or scripts.
See Scripting Reference.
User Forums
The Designer Forum is a meeting place for professionals who are interested in discussing issues
related to Designer. 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 information, see www.adobeforums.com.
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 Developer Center.
2
Scripting Using Designer
As part of the form design process, a form developer can use calculations and scripts to provide a
richer user experience. You can add calculations 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 supports two scripting languages, each geared towards the needs of a particular type of
form developer. FormCalc is a straightforward, 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 without the use of scripts. However, through
scripting, you can manipulate and control almost all aspects of your form design.
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.
NOTE:
How scripting works
Designer 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;
3
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.
RELATED LINKS:
Events
Objectsthat support calculations and scripts
Understandingrelationships between objects in the ObjectLibrary
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.
Objects that support calculations and
scripts
Barcodes
Circle
Button
Content Area
Check Box
Line
Date/Time Field
Rectangle
Decimal Field
Image
Signature Field
Subform Sets
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
4
Objects that do not support calculations
and scripts
Objects that support calculations and
scripts
Objects that do not support calculations
and scripts
Radio Button
Reset Button
Subform
Table (including body rows, header rows, and
footer rows)
Text Field
RELATED LINKS:
Understandingrelationships between objects in the ObjectLibrary
Understanding relationships between objects in the Object
Library
When you create calculations and scripts in Designer, 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
Scripting Objects section, 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 object.
For example, if you want to browse the properties and methods that are available for a Date/Time
Field object in Designer, 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, and the corresponding XML Form Architecture object.
5
Standard Object Library
Object
XML Form Architecture
Object (Base)
Barcodes
field
barcode
Button
field
button
Check Box
field
checkButton
Date/Time Field
field
dateTime
Decimal Field
field
numericEdit
Signature Field
field
signature
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 footer
rows)
subform
N/a
Text Field
field
textEdit
RELATED LINKS:
Objectsthat support calculations and scripts
6
XML Form Architecture
Object (UI)
Script Editor
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
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 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.
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.
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. (See To setthe
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
7
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 working session.
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
generator processes the form.
•
Client and server Calculations and scripts execute while the server application (for
example, Forms) 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.
Event Propagation
To see the Event Propagation checkbox go to Tools > Options dialog and in the Workspace tab,
select the Display Event Propagation Option checkbox.
You can make your 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. A few examples of global events
are:
8
•
An enter/exit/mouseEnter/mouseExit event that colors the active field.
•
A change event that track keystrokes for a form session.
Configuring Designer for Scripting
To show the Script Editor
1)
Select Window > Script Editor.
You can use the Expand button to quickly dock or undock the Script Editor when it is
displayed in the Designer workspace.
NOTE:
To change from single-line to multiline view
1)
Drag the Script Editor palette bar until the palette is the required size.
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.
NOTE:
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.
9
To set the default scripting language for the current form
1)
Select Edit > 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 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 scripting language for a form template
10
1)
Create a new form design.
2)
Select Edit > 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 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.
This procedure only sets the value of the default processing application for the current
instance of the form.
NOTE:
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.
To set the default processing application
1)
Select Edit > Form Properties.
2)
Click the Defaults tab.
3)
Select your default processing application from the Default Run At list.
This procedure only sets the value of the default processing application for the current
instance of the form.
NOTE:
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.
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 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.
11
To change the default processing application for a form
template
1)
Create a new form design.
2)
Select Edit > 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 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 uses in these tabs. Otherwise, Designer displays rectangles where the language-specific characters should be.
12
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 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 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 Tocheck script syntax.
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
JavaScriptDebugging.
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 when you import or save a form, or preview
a form using the Preview PDF tab.
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.
13
Workspace location
Purpose
Binding tab in the
Object palette
Every Designer 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, 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.
14
Creating Calculations and Scripts
Designer 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 Examplesof Common
Scripting Tasks.
Creating calculations and scripts in Designer 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 that support scripting, see Objectsthat support calculations and scripts.
•
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.
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.
15
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:
•
horizontalValue
•
x_value
•
xLetter
•
hValue
For more information and a list of the XML Form Object Model property, method, and object
names, see Scripting Reference.
RELATED LINKS:
Namingvariables
CreatingCalculations and Scripts
Choosing a scripting language
Designer 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 to reduce the amount of new scripting you need to create.
NOTE:
Designer 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 working session.
16
Effective March 10, 2012, Adobe is deprecating the Guides capabilities of Adobe® LiveCycle® ES.
The Guides functionality is available for upgrade purposes only and will be removed from the product
after two major releases.
NOTE:
The following table highlights some of the key differences between FormCalc and JavaScript.
FormCalc
JavaScript
Native Adobe calculation language valid in
Designer and Forms
Standard scripting language used in many
popular software applications
Shorter scripts (typically one line only)
Supports script looping
Potential for longer scripts, if necessary, with
the ability to use looping
Not supported by form Guides (deprecated)
Supported by form Guides (deprecated)
Contains a variety of useful built-in
functions to reduce the amount of scripting
required to accomplish common form
design tasks
Provides access to the Acrobat Object Model
and the JavaScript capabilities of 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 and Forms
supported platforms
Compatible on all Designer and Forms
supported platforms
RELATED LINKS:
UsingFormCalc
UsingJavaScript
Creatingand Reusing JavaScript Functions
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.
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.
17
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.
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 to help you create reference
syntaxes for your calculation or script. For example, add the following JavaScript 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 objects that support scripting, see Objectsthat
support calculations and scripts.
To create a calculation or script
18
1)
Select an object on your form design that supports events. For example, add a button to a new,
blank form.
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, Adobe document
services).
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.
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.
NOTE:
5)
In the Script Source field, insert your FormCalc calculation or JavaScript script. You can take
advantage of the statement completion functionality of Designer to help you create reference
syntaxes for your calculation or script. For example, add the following JavaScript 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 objects that support scripting, see Objectsthat
support calculations and scripts.
RELATED LINKS:
UsingFormCalc
UsingJavaScript
Events
Touse statement completion to create calculations andscripts
Determiningwhen to run your calculation or script
Toview scripting events and scripts
Determiningwhere to run your calculation or script
Testingand debugging calculations and scripts
19
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.
IMPORTANT: 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 the Developer
Center.
RELATED LINKS:
CreatingCalculations and Scripts
To create a calculation orscript
t
Toreplace text or other items
Touse statement completion to create calculations andscripts
Determiningwhen to run your calculation or script
Toview scripting events and scripts
Determiningwhere to run your calculation or script
Testingand debugging calculations and scripts
To replace text or other items
You can automatically replace text. For example, you can replace Corp. with Corporation.
20
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.
IMPORTANT: 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 the Developer
Center.
RELATED LINKS:
CreatingCalculations and Scripts
Tofind text or other items
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
ReferencingObjects in Calculations and Scripts.
1)
Type the name of a form design object, property, or a valid FormCalc shortcut, followed by a
period.
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.
RELATED LINKS:
Referencingobject properties and values
21
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.
RELATED LINKS:
ReferencingObjects in Calculations and Scripts
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, 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.
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 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:
22
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.
RELATED LINKS:
Toview scripting events and scripts
Events
Determiningwhere to run your calculation or script
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.
23
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.
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.
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.
NOTE:
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.
24
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, you must specify the location where you want
the calculation or script to run.
Unless you are using server-based processing such as Forms, you should ensure that all of your
calculations and scripts are set to run on the client application (for example, on Acrobat, a web
browser, or the Mobile Workspace app).
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.
For more information, see Determining whento run your calculationor script.
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.
RELATED LINKS:
25
Events
Determiningwhen to run your calculation or script
Toview scripting events and scripts
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 includes three primary methods for testing and debugging your calculations and scripts:
•
Using the Designer workspace palettes. For more information, see Usingthe workspace to
debug calculations and scripts .
•
For JavaScript only, using the JavaScript Debugger to assist you in testing your scripts. For
more information about using the debugger, see JavaScript Debugging.
•
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
RELATED LINKS:
Usingthe workspace to debug calculations and scripts
Workingwith a Host Application
Workingwith the Event Model
26
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.
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.
NOTE:
1)
In the Script Editor, select Tools > Check Script Syntax.
RELATED LINKS:
UsingFormCalc
UsingJavaScript
Objectsthat support calculations and scripts
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.
... 
var oDB = xfa.sourceSet.nodes.item(nIndex); 
27
... 
// 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:
object.
28
You can store the cloned data connection node in a variable or a variable defined in a script
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 interaction.
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.
RELATED LINKS:
Process events
Interactive events
29
Application events
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.
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.
30
RELATED LINKS:
Interactive events
Application events
calculate event
docReady event
form:ready event
indexChange event
initialize event
layout:ready event
validate event
Determining when to run your calculation or script
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
31
•
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.
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.
The following image displays the general flow of events for form fillers who use the keyboard
to select an object and change its value.
RELATED LINKS:
change event
click event
enter event
exit event
full event
mouseDown event
32
mouseEnter event
mouseExit event
mouseUp event
postOpen event
postSign event
preOpen event
preSign event
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
For example, the following image displays the general flow of events for the preSave event.
33
34
35
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.
RELATED LINKS:
docClose event
postPrint event
postSave event
postSubmit event
prePrint event
preSave event
preSubmit event
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:
36
•
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.
•
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 Calculatingthe field sums.
RELATED LINKS:
Events
Process events
37
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
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.
38
Scripting against an object's 'this.rawValue' does not work. Use the event model property $event.fullTextinstead to get the object's current value.
NOTE:
For a detailed example of using the change event, see Gettingthe current or previous value of a
drop-down list.
RELATED LINKS:
Events
Interactive events
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.
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 Help.
NOTE:
Type
Interactive event
Support
Client application
Availability
Acrobat and Adobe Reader
yes
HTML browser
yes
Version
XFA 2.1
39
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 Changingthe visual properties of an object on
the client.
RELATED LINKS:
Events
Interactive events
preSubmit event
docClose event
Description
Initiates at the very end of processing a form, only if all form validations complete with no errors.
Type
Application event
Support
Client application
Acrobat and Adobe Reader
yes
HTML browser
no
Version
XFA 2.1
40
Availability
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.
RELATED LINKS:
Events
Application events
Process events
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
41
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.
RELATED LINKS:
Events
Application events
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
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.
42
For a detailed example of using the enter event, see Highlightingfields in response to form filler
interaction.
RELATED LINKS:
Events
Interactive events
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.
43
For a detailed example of using the exit event, see Highlightingfields in response to form filler
interaction.
RELATED LINKS:
Events
Interactive events
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.
The form:ready event only applies to Design View objects, and does not apply to Master Page
objects (see Processevents).
NOTE:
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.
44
RELATED LINKS:
Events
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.
RELATED LINKS:
Events
Interactive events
45
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.
This event is received only by the subform instances that are controlled by the instance manager;
the event is ignored for subform sets.
NOTE:
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.
RELATED LINKS:
Events
Process events
46
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.
RELATED LINKS:
Events
Process events
47
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.
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.
RELATED LINKS:
Events
48
Process events
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.
RELATED LINKS:
Events
49
Interactive events
click event
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 Highlightingfields in response to form
filler interaction.
RELATED LINKS:
Events
50
Interactive events
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 Highlightingfields in response to form
filler interaction.
RELATED LINKS:
Events
51
Interactive events
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.
RELATED LINKS:
Events
52
Interactive events
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
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.
RELATED LINKS:
Events
53
Interactive events
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.
RELATED LINKS:
Events
Application events
54
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.
RELATED LINKS:
Events
Application events
55
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.
RELATED LINKS:
Events
Interactive events
56
postSubmit event
Description
Initiates immediately after a form submits data to the host through the HTTP protocol.
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.
NOTE:
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.
RELATED LINKS:
Events
Application events
57
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.
RELATED LINKS:
Events
Interactive events
58
prePrint event
Description
Initiates immediately before the process of rendering a form for printing begins. You cannot cancel
printing using this event.
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.
IMPORTANT:
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.
RELATED LINKS:
Events
Application events
59
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.
RELATED LINKS:
Events
Application events
60
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.
RELATED LINKS:
Events
Interactive events
61
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.
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.
NOTE:
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.
RELATED LINKS:
Events
62
Application events
preSave event
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.
Because validations are performed against the content of the form, they cannot be used to verify
presentation formatting caused by field patterns.
NOTE:
Type
Processing event
Support
Client application
Availability
Acrobat and Adobe Reader
yes
HTML browser
yes
Version
XFA 2.1
63
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 Settinga field as required at run time.
RELATED LINKS:
Events
Process events
64
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-infunction syntax.
FormCalc function
Description
JavaScript method
equivalent
Abs(n1)
Returns the absolute
value of a numeric
value or expression.
Math.abs(n1)
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 another
string.
String.search(s1)
Avg(n1 [, n2... ] )
Evaluates a set of
number values and/or
expressions and returns
the average of the
non-null elements
contained within that
set.
None
Ceil(n1)
Returns the whole
number greater than or
equal to a given
number.
Math.ceil(n1)
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 ... ])
65
FormCalc function
66
Description
JavaScript method
equivalent
Count(n1 [, n2...])
Evaluates a set of values
and/or expressions and
returns the number of
non-null elements
contained within the
set.
None
CTerm(n1, n2, n3)
Returns the number of
periods needed for an
investment earning a
fixed, but
compounded, interest
rate to grow to a future
value.
None
Date()
Returns the current
system date as the
number of days since
the epoch.
Date.getDate()
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 date string.
The JavaScript Date object
does not use the 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 reference syntax
to an existing object.
None
FormCalc function
Description
JavaScript method
equivalent
Floor(n1)
Returns the largest
whole number that is
less than or equal to the
given value.
Math.floor(n1)
Format(s1, s2)
Formats the given data
according to the
specified picture
format string.
None
FV(n1, n2, n3)
Returns the future
value of consistent
payment amounts
made at regular
intervals at a constant
interest rate.
None
Get(s1)
Downloads the
contents of the given
URL.
None
HasValue(v1)
Determines whether
the given parameter is a
valid reference syntax
with a non-null,
non-empty, or
non-blank value.
None
IPmt(n1, n2, n3, n4,
n5)
Returns the amount of
interest paid on a loan
over a set time.
None
IsoDate2Num(d1)
Returns the number of
days since the epoch,
given a valid date
string.
None
IsoTime2Num(d1)
Returns the number of
milliseconds since the
epoch, given a valid
time string.
None
Left(s1, n1)
Extracts a specified
number of characters
from a string, starting
with the first character
on the left.
String.substring(n1
, n2)
67
FormCalc function
68
Description
JavaScript method
equivalent
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 format style.
None
LocalTimeFmt( [ n1 [,
k1 ] ] )
Returns a localized
time format string,
given a time format
style.
None
Lower(s1 [, k1 ] )
Converts all uppercase
characters within a
specified string to
lowercase characters.
String.toLowerCase(
s1)
Ltrim(s1)
Returns a string with
all leading white space
characters removed.
None
You can use JavaScript regular
expressions to perform this
operation.
Max(n1 [, n2... ] )
Returns the maximum
value of the non-null
elements in the given
set of numbers.
Math.max(n1, n2)
Min(n1 [, n2... ] )
Returns the minimum
value of the non-null
elements of the given
set of numbers.
Math.min(n1, n2)
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 a discount
rate and a series of
periodic future cash
flows.
None
Num2Date(n1[, f1 [,
k1 ] ] )
Returns a date string
given a number of days
since the epoch.
None
FormCalc function
Description
JavaScript method
equivalent
Num2GMTime(n1 [,f1 [,
k1 ] ] )
Returns a GMT time
string given a number
of milliseconds from
the epoch.
None
Num2Time(n1 [,f1 [,
k1 ] ] )
Returns a time string
given a number of
milliseconds from the
epoch.
None
Oneof(s1, s2 [, s3...
] )
Returns true (1) if a
value is in a given set
and false (0) if it is not.
None
This function is similar to the
String.search(s1)
method and
String.match(express
ion) method.
Parse(s1, s2)
Analyzes the given data
according to the given
picture format.
None
Pmt(n1, n2, n3)
Returns the payment
for a loan based on
constant payments and
a constant interest rate.
None
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 period of time.
None
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 constant
payments at a constant
interest rate.
None
Rate(n1, n2, n3)
Returns the compound
interest rate per period
required for an
investment to grow
from present to future
value in a given period.
None
69
FormCalc function
70
Description
JavaScript method
equivalent
Ref()
Returns a reference to
an existing object.
None
Replace(s1, s2 [, s3
] )
Replaces all
occurrences of one
string with another
within a specified
string.
String.replace(s1,
s2)
Right(s1, n1)
Extracts several
characters from a given
string, beginning with
the last character on
the right.
String.substring(n1
, n2)
Round(n1 [, n2 ] )
Evaluates a given
numeric value or
expression and returns
a number rounded to
the given number of
decimal places. For
more accurate results,
set a legacy flag in
xfa.xci. To switch to the
default behavior,
remove the legacy flag.
Math.round(n1)
Rtrim(s1)
Returns a string with
all trailing white space
characters removed.
None
You can use JavaScript regular
expressions to perform this
operation.
Space(n1)
Returns a string
consisting of a given
number of blank
spaces.
None
Str(n1 [, n2 [, n3 ]
] )
Converts a number to a
character string.
FormCalc formats the
result to the specified
width and rounds to
the specified number of
decimal places.
String(n1)
or
Number.toString(rad
ix)
Stuff(s1, n1, n2 [,
s2 ] )
Inserts a string into
another string.
None
Description
JavaScript method
equivalent
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 of numbers.
None
Term(n1, n2, n3)
Returns the number of
periods required to
reach a given future
value from periodic
constant payments into
an interest-bearing
account.
None
Time()
Returns the current
system time as the
number of milliseconds
since the epoch.
Date.getTime()
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, given a time
string.
None
TimeFmt([n1 [, k1 ] ]
)
Returns a time format,
given a time format
style.
None
UnitType(s1)
Returns the units of a
unitspan. A unitspan is
a string consisting of a
number followed by a
unit name.
None
UnitValue(s1 [, s2 ]
)
Returns the numeric
value of a measurement
with its associated
unitspan after an
optional unit
conversion.
None
Upper(s1 [, k1 ] )
Converts all lowercase
characters within a
string to uppercase.
String.toUpperCase(
)
FormCalc function
71
FormCalc function
Description
JavaScript method
equivalent
Uuid(n1)
Returns a Universally
Unique Identifier
(UUID) string to use as
an identification
method.
None
Within(s1, s2, s3)
Returns true (1) if the
test value is within a
given range, and false
(0) if it is not.
String.search(s1)
WordNum(n1 [, n2 [,
k1 ] ] )
Returns the English
text equivalent of a
given number.
None
RELATED LINKS:
Using FormCalc
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, FormCalc is the default scripting language in all scripting locations with JavaScript
as the alternative. For information on setting your default scripting language, see ConfiguringDesigner for Scripting.
If you are developing forms for use with a server-based process (for example, using Foms),
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.
IMPORTANT:
FormCalc treats each new line in the Script Editor as a new expression to evaluate.
RELATED LINKS:
Using JavaScript
72
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
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.
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).
73
Syntax notation
Replacement values
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.
RELATED LINKS:
Creating basic calculations
Using FormCalc
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
"abc"
74
Equivalent to
"abc"
Result
abc
Expression
Equivalent to
Result
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)
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
Highest
Operator
=
(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 with a single numeric
field, add the following calculation to the calculate event in the Script Editor.
Then, when you click the Preview PDF tab to view the completed form, the value of the simple
expression appears in the text field.
75
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 and Acrobat correctly.
RELATED LINKS:
Using FormCalc
Using JavaScript
Using JavaScript
To allow form designers more flexibility and scripting power, Designer supports the use of JavaScript version 1.6 or earlier in all situations that support scripting.
Form developers who are familiar with JavaScript can apply their existing expertise directly to
Designer. Designer 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 reference
syntax provide you with easy manipulation of form values and data.
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.
NOTE:
RELATED LINKS:
Creating scripts using JavaScript
76
Creating scripts using JavaScript
Creating scripts in Designer 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 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 reference syntax.
Specifically, you must know how to correctly use the XML Form Object Model reference syntax to
access objects on your form design.
This table outlines the key concepts for developing scripts in JavaScript for Designer. The table also
provides the location for more information on each concept within the Designer Help .
Key concept
For more information see...
Creating references to object properties and
values, including using the resolveNode
method.
Referencingobject properties and values
resolveNode
Touse statement completion to create
calculations and scripts
Using the host and event models to test and
debug your form.
Testingand debugging calculations and
scripts
Referencingobject properties and values
Using a script object to reuse your existing
JavaScript functions.
Creatingand Reusing JavaScript Functions
In addition to the resources available in the Designer Help , the Developer Centercontains extensive
scripting resources and documentation.
RELATED LINKS:
Enforcing strict scoping rules in JavaScript
To attach a JavaScript script to an object
Using JavaScript
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.
77
Strict scoping was introduced in Designer 8.1 to improve the run time and memory usage of a form.
Strict scoping is enabled, by default, in Designer, for new forms. For old forms the option to enable
strict scoping is available.
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 ().
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. TShe pieces of script can be variables or functions.
78
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>
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> 
79

/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.1, the function bar()
does not execute. The reason is because function bar() is available only from within the initialized
script of field1.
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
80
Reader 9.0 and later, strict scoping does not release all the JavaScript variables. The exception 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 Run-time tab.
2)
Select Enforce Strict Scoping Rules In JavaScript , if the option is available, and then click OK.
If the option to enforce strict scoping rules is not available in the Run-time tab, then strict
scoping is already enabled.
NOTE:
RELATED LINKS:
Using JavaScript
To attach a JavaScript script to an object
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
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
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:
or F10 to display a list of JavaScript functions.
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.
81
RELATED LINKS:
Using JavaScript
82
Variables
You can define form variables in Designer 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 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 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.
.
83
4)
Click once in the box to the right and type the text you want to associate with the variable.
The variable appears in the Hierarchy palette at the form level.
A.New form variable
To define a text variable
1)
Select Edit > 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.
.
The variable appears in the Hierarchy palette at the form level.
A.New form variable
84
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 view a text variable definition
1)
Select Edit > 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)
.
To delete a text variable
1)
Select Edit > 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.
IMPORTANT: 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 Scripting
Reference.
For example, create the following form variable definitions.
85
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 )
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;
Using and modifiying form variables with scripting in XFA forms can cause the document
message bar in Acrobat and Adobe Reader to display a signature validation status warning indicating
that the signature validity is unknown due to subsequent changes to the document.
NOTE:
86
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
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.
NOTE:
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.
87
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.
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.
88
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:
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
89
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
Scripting Reference.
RELATED LINKS:
ReferencingObjects in Calculations and Scripts
Referencingunnamed and repeated objects
Referencingthe current object
FormCalcreference syntax shortcuts
Referencing unnamed and repeated objects
Designer supports the capability to create both unnamed objects and multiple objects with the same
name. You can still create calculations and scripts to access and modify properties and values of
unnamed objects by using the number sign (#) notation and object occurrence 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.
90
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
By default, if you do not specify an occurrence value for an object, the reference syntax accesses
the first occurrence of that object.
NOTE:
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:
xfa.form.form1.#subform[1].TextField1.rawValue // FormCalc 
xfa.resolveNode("xfa.form.form1.#subform[1].TextField1").rawValue; //
JavaScript
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.
NOTE:
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
For more information on the resolveNode method, see resolveNode.
RELATED LINKS:
ReferencingObjects in Calculations and Scripts
Referencingobject properties and values
Referencingthe current object
FormCalcreference syntax shortcuts
91
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
RELATED LINKS:
ReferencingObjects in Calculations and Scripts
Referencingobject properties and values
Referencingunnamed and repeated objects
FormCalcreference syntax shortcuts
FormCalc reference syntax shortcuts
To make accessing object properties and values easier, FormCalc includes shortcuts to reduce the
effort required to create references. This section describes the reference syntax shortcuts for FormCalc.
Current field or object
Refers to the current field or object
Notation
$
Example
$ = "Tony Blue"
92
The above example sets the value of the current field or object to Tony Blue.
Data model root of xfa.datasets.data
Represents the root of the data model xfa.datasets.data.
Notation
$data
Example
$data.purchaseOrder.total
is equivalent to
xfa.datasets.data.purchaseOrder.total
Form object event
Represents the current form object event.
Notation
$event
Example
$event.name
is equivalent to
xfa.event.name
For more information see Working with the Event Model.
Form model root
Represents the root of the form model xfa.form.
93
Notation
$form
Example
$form.purchaseOrder.tax
is equivalent to stating
xfa.form.purchaseOrder.tax
Host object
Represents the host object.
Notation
$host
Example
$host.messageBox("Hello world")
is equivalent to
xfa.host.messageBox("Hello world")
For more information, see Working with a Host Application.
Layout model root
Represents the root of the layout modelxfa.layout.
Notation
$layout
Example
$layout.ready
is equivalent to stating
94
xfa.layout.ready
Collection of data record
Represents the current record of a collection of data, such as from an XML file.
Notation
$record
Example
$record.header.txtOrderedByCity
references the txtOrderedByCity node within the header node of the current XML data.
Template model root
Represents the root of the template model xfa.template.
Notation
$template
Example
$template.purchaseOrder.item
is equivalent to
xfa.template.purchaseOrder.item
Data model root of xfa.datasets
Represents the root of the data modelxfa.datasets.
Notation
!
95
Example
!data
is equivalent to
xfa.datasets.data
Select all form objects
Selects all form objects within a given container, such as a subform, regardless of name, or selects all
objects that have a similar name.
You can use the ‘*’ (asterisk) syntax with JavaScript if it used with the resolveNode method.
Notation
*
Example
For example, the following expression selects all objects named item on a form:
xfa.form.form1.item[*]
Search for objects that are part of a subcontainer
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.
You can use the ‘..’ (double period) syntax with JavaScript if it used with the resolveNode method.
Notation
..
Example
The expressionSubform_Page..Subform2means locate the nodeSubform_Page(as usual)
and find a descendant ofSubform_PagecalledSubform2.
96
Using the example tree above,
Subform_Page..TextField2
is equivalent to
Subform_Page.Subform1[0].Subform3.TextField2[0]
becauseTextField2[0]is in the firstSubform1node that FormCalc encounters on its search.
As a second example,
Subform_Page..Subform3[*]
returns all fourTextField2objects.
Denote an unnamed object or specify a property
The number sign (#) notation is used to denote one of the following items in a reference syntax:
•
An unnamed object
•
Specify a property in a reference syntax if a property and an object have the same name
You can use the ‘#’ (number sign) syntax with JavaScript if it used with the resolveNode method.
Notation
#
Example
The following reference syntax accesses an unnamed subform:
xfa.form.form1.#subform
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
97
Occurrence value of an object
The square bracket ([ ]) notation denotes the occurrence value of an object.
In language-specific forms for Arabic, Hebrew, Thai, and Vietnamese, the reference syntax is always
on the right (even for right-to-left languages).
Notation
[ ]
Example
To construct an occurrence value reference, place square brackets ([ ]) after an object name, and
enclose within the brackets one of the following values:
•
[ n ], wherenis 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[*]
•
98
This expression refers to all objects with a name ofQuantitythat are siblings to the first
occurrence ofQuantityfound by the reference.
Using the tree for reference, these expressions return the following objects:
•
Subform_Page.Subform1[*]returns bothSubform1objects.
•
Subform_Page.Subform1.Subform3.TextField2[*]returns
twoTextField2objects.Subform_Page.Subform1resolves to the
firstSubform1object on the left, andTextField2[*]evaluates relative to
theSubform3object.
•
Subform_Page.Subform1[*].TextField1returns both of
theTextField1instances.Subform_Page.Subform1[*]resolves to
bothSubform1objects, andTextField1evaluates relative to theSubform1objects.
•
Subform_Page.Subform1[*].Subform3.TextField2[1]returns the second and
fourthTextField2objects from the left.Subform_Page.Subform1[*]resolves to
bothSubform1objects, andTextField2[1]evaluates relative to theSubform3objects.
•
Subform_Page.Subform1[*].Subform3[*]returns both instances of
theSubform3object.
•
Subform_Page.*returns bothSubform1objects and theSubform2object.
•
Subform_Page.Subform2.*returns the two instances of theNumericField2object.
•
You can use the ‘ [ ]’ (square bracket) syntax with JavaScript if it used with the resolveNode
method.
•
RELATED LINKS:
ReferencingObjects in Calculations and Scripts
99
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 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)
100
(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.
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.
101
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 Referencingobject properties and values.
Example
For example, using the script object example from Toadd script to a script object, place the following
JavaScript script on the exit event for a text field. Test the form using the Preview PDF tab.
102
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.
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
tion.
to view the fragment informa-
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.
103
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.
You can also create a script fragment by dragging the script object from the Hierarchy
palette to the Fragment Library palette.
NOTE:
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:
6)
•
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.
Click OK.
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:
104
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
RELATED LINKS:
Creating and Reusing JavaScript Functions
To create a script object
To add script to a script object
105
Debugging Calculations and Scripts
Designer 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 disadvantage 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 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 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 Usingthe workspace to debug calculations
and scripts.
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.
106
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);
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 messageBoxmethod at runtime.
IMPORTANT:
For more informatin about using the messageBox, see messageBox
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..
JavaScript Debugging
If you use the JavaScript language for a script, you can use the console.println("string")
function to output information to the JavaScript 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.
107
To enable the JavaScript Debugger for Designer and execute code from the JavaScript Console,
enable JavaScript and the JavaScript Debugger in Acrobat Professional.
You can enable the JavaScript Debugger in Adobe Reader if you have Acrobat Reader DC extensions 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).
NOTE:
To enable the JavaScript Debugger for Designer
1)
Start Designer.
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, click the Preview PDF tab.
12) Press Ctrl+J to open the JavaScript Debugger.
To prevent the JavaScript Debugger from disappearing in Designer
If the JavaScript Debugger from Acrobat is active and it disappears when you click components in
the Designer 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.
108
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
1)
Highlight the portion in the console window and press either Enter on the numeric keypad or
Ctrl+Enter on the regular keyboard.
To evaluate a single line of code
1)
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
1)
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
1)
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
109
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 Applications 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).
RELATED LINKS:
Using the workspace to debug calculations and scripts
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.
Master pages
To debug master pages, drop a different object on each master page to find out which one is specified.
110
First page in a form
Designer 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, 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 
111
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 JavaScript in the Script Editor. If not, you may see a message indication that Designer 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.
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:
112
•
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 srcof 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 evencauses 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.
113
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 to render a form in HTML format, then during the
pre-rendering process the host application is Forms.
Once you render a form and view it in a client application such as Acrobat, Adobe Reader, or an
HTML browser, then the client application becomes the host application.
Designer 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
114
Methods
appType
beep
calculationsEnabled
exportData
currentPage
gotoURL
language
importData
name
messageBox
numPages
pageDown
platform
pageUp
title
print
Properties
Methods
validationsEnabled
resetData
variation
response
version
setFocus
For more information about the host scripting model properties and methods, see the Developer
Center.
Comparing the host scripting model functionality
This table lists the Designer 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 Help , or
see the 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 [, BOOLEAN param2 ]
])
doc.exportXFAData(cPath [,
bXDP ])
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 [, STRING param2 [,
INTEGER param3 [, INTEGER
param4 ] ] ])
app.alert(cMsg [, nIcon [,
nType [, cTitle ] ] ])
115
Host scripting model properties and
methods
JavaScript Object Model from Acrobat
equivalent
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 param2,
INTEGER param3, BOOLEAN
param4, BOOLEAN param5,
BOOLEAN param6, BOOLEAN
param7, BOOLEAN param8)
doc.print([ bUI [, nStart [,
nEnd [, bSilent [,
bShrinkToFit [,
bPrintAsImage [, bReverse [,
bAnnotations ] ] ] ] ] ] ] ])
xfa.host.resetData( [ STRING
param ] )
doc.resetForm([ aFields ])
xfa.host.response( STRING
param1 [, STRING param2 [,
STRING param3 [, BOOLEAN
param4] ] ])
app.response(cQuestion [,
cTitle [, cDefault [,
bPassword ] ] ])
xfa.host.setFocus( STRING
param )
field.setFocus()
(Deprecated)
xfa.host.title
doc.title
xfa.host.variation
app.viewerVariation
xfa.host.version
app.viewerVersion
RELATED LINKS:
ReferencingObjects in Calculations and Scripts
116
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
117
Properties
Methods
selEnd
selStart
shift
soapFaultCode
soapFaultString
target
For more information about the event scripting model properties and methods, see the Developer
Center.
118
Moving from Scripting in Acrobat to Designer
Designer includes extensive scripting capabilities, including support for the most common JavaScript objects from Acrobat. When you convert an Acrobat form to Designer, 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 scripting differs from scripting
in Acrobat in several ways:
Designer workspace
In the Designer workspace, you can change object properties and behaviors on your form
without requiring you to create scripts.
Scripting languages
Designer 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 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. However, you should consider JavaScript from Acrobat only for tasks that you
cannot perform using the XML Form Object Model in Designer. 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 form, including Acrobat
forms that you have converted using Designer. When you view a Designer form in Acrobat, all
JavaScript tools are unavailable.
For more information about converting Acrobat scripting to Designer, see the article
Converting Acrobat JavaScript for Use inDesigner Forms in the Developer Center.
Converting Acrobat forms that contain scripts
One of the first steps in converting a form from Acrobat to Designer is to determine how much of
the Acrobat scripting is supported by Designer and how much you must convert.
119
In general, you should convert all Acrobat scripting to an equivalent in Designer. Designer scripting
takes full advantage of the highly structured nature of Designer 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, see the article Converting
Acrobat JavaScript for Use inDesigner Forms in the Developer Center.
RELATED LINKS:
Moving from Scripting in Acrobat to Designer
Using JavaScript objects from Acrobat in Designer
JavaScript objects from Acrobat supported in Designer
Using JavaScript objects from Acrobat in Designer
In Designer, 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:
console.println("This message appears in the JavaScript
Console.");
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);
In Designer, you must ensure that the scripting language for the event is set to JavaScript so that
the script will execute correctly at run time.
NOTE:
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) { 
... 
}
120
This example uses a fully qualified reference syntax to reference the text For more information
about referencing form design objects, see Referencingobject properties and values.
NOTE:
When working with JavaScript from Acrobat in Designer, remember these points:
•
In Designer, 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, 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, see the article
Converting Acrobat JavaScript for Use inDesigner Forms in the Developer Center.
RELATED LINKS:
Moving from Scripting in Acrobat to Designer
Converting Acrobat forms that contain scripts
JavaScript objects from Acrobat supported in Designer
JavaScript objects from Acrobat supported in Designer
The following table lists the availability of the most commonly used Acrobat objects, properties, and
methods in Designer, and provides information on any equivalent functionality in Designer.
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 functionality is listed, no direct Designer 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
support
JavaScript-equiva
lent in Designer
Comments
Annotobject properties and methods
All properties and methods
Yes
None
Only forms with a
fixed layout support
the annotation layer.
appobject properties
121
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
Comments
calculate
No
None
Designer includes
the
execCalculate
method which
initiates
thecalculateeven
t.
execCalculate
language
Yes
xfa.host.lan
guage
See the
languageproperty.
language
monitors
Yes
None
platform
Yes
xfa.host.pla
tform
plugins
Yes
None
toolbar
Yes
None
viewerType
Yes
xfa.host.app
Type
See the
appTypeproperty.
appType
viewerVariation
Yes
xfa.host.var
iation
See the
variationpropert
y.
variation
viewerVersion
Yes
xfa.host.ver
sion
See the
versionproperty.
version
addMenuItem
Yes
None
addSubMenu
Yes
None
addToolButton
Yes
None
alert
Yes
xfa.host.mes
sageBox()
See the
platformproperty.
platform
appobject methods
122
See the
messageBoxmeth
od.
messageBox
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
beep
Yes
xfa.host.bee
p()
browseForDoc
Yes
None
clearInterval
Yes
None
clearTimeOut
Yes
None
execDialog
Yes
None
execMenuItem
Yes
None
getNthPluginName
Yes
None
getPath
Yes
None
goBack
Yes
None
goForward
Yes
None
hideMenuItem
Yes
None
hideToolbarButton
Yes
None
launchURL
Yes
None
listMenuItems
Yes
None
listToolbarButtons
Yes
None
mailGetAddrs
Yes
None
mailMsg
Yes
None
Comments
See the
beepmethod.
beep
Executes the
specified menu
command. Use this
method in Designer
for File menu
commands.
Designer includes
the
gotoURLmethod
that loads a specified
URL into the client
application, such as
Acrobat or Adobe
Reader.
gotoURL
123
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
newDoc
Yes
None
newFDF
No
None
openDoc
Yes
None
openFDF
No
None
popUpMenuEx
Yes
None
popUpMenu
Yes
None
removeToolButton
Yes
None
response
Yes
xfa.host.res
ponse()
setInterval
Yes
None
setTimeOut
Yes
None
trustedFunction
Yes
None
trustPropagatorFun
ction
Yes
None
Bookmark object properties and methods
All properties and methods
Yes
None
author
Yes
None
baseURL
Yes
None
bookmarkRoot
Yes
None
calculate
No
None
dataObjects
Yes
None
docobject properties
124
Comments
This method can
only be executed
during batch,
console, or menu
events.
See the
responsemethod.
response
This method is only
available during
batch, console, and
application
initialization.
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
delay
No
None
dirty
Yes
None
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
media
Yes
None
metadata
Yes
xfa.form.des
c
modDate
Yes
None
mouseX mouseY
Yes
None
noautocomplete
Yes
None
nocache
Yes
None
Comments
This JavaScript script
for Designer saves a
copy of a form and
tests whether the
form has changed:
var sOrigXML =
xfa.data.saveX
ML; if
(sOrigXML !=
xfa.data.saveX
ML) {...}
See the descobject.
desc
125
JavaScript in Acrobat
126
Designer
support
JavaScript-equiva
lent in Designer
Comments
numFields
Yes
xfa.layout.p
ageContent()
The
pageContentmet
hod 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.
pageContent
numPages
Yes
xfa.host.num
Pages
or
xfa.layout.a
bsPageCount(
)
xfa.layout.p
ageCount()
The
numPagesproperty
returns the page
count for the
rendered form in the
client. See also the
absPageCountan
d
pageCountmethod
s.
numPages
absPageCount
pageCount
pageNum
Yes
xfa.host.cur
rentPage
See the
currentPageprop
erty.
currentPage
pageNum--
Yes
xfa.host.cur
rentPage-or
xfa.host.pag
eUp()
See the
currentPageprop
erty or the
pageUpmethod.
currentPage
pageUp
pageNum++
Yes
xfa.host.cur
rentPage++
or
xfa.host.pag
eDown()
See the
currentPageprop
erty or the
pageDownmethod.
currentPage
pageDown
path
Yes
None
securityHandler
Yes
None
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
Comments
templates
No
None
Use subform objects
in Designer, and use
properties and
methods to add,
remove, move, and
set subform
instances.
Addand remove
subform instances
using scripting
title
Yes
xfa.host.tit
le
See title.
addAnnot
Yes
None
addField
No
None
addIcon
Yes
None
addLink
No
None
addRecipientListCr
yptFilter
Yes
None
addScript
Yes
None
addThumbnails
No
None
addWatermarkFromFi
le
Yes
None
docobject methods
You must use forms
that have a fixed
layout in Designer,
and then use the
instanceManage
r object to add,
remove, and set the
number of instances
of a particular object.
instanceManager
For more
information, see
Addand remove
subform instances
using scripting.
127
JavaScript in Acrobat
128
Designer
support
JavaScript-equiva
lent in Designer
addWatermarkFromTe
xt
Yes
None
addWeblinks
Yes
None
appRightsSign
Yes
None
appRightsValidate
Yes
None
bringToFront
Yes
None
calculateNow
No
xfa.form.rec
alculate(1);
or
execCalculat
e()
closeDoc
Yes
None
createDataObject
Yes
None
Comments
recalculate
The
recalculatemet
hod forces a specific
set of scripts
oncalculateeven
ts to initiate. Boolean
value indicates
whetherTrue(defaul
t) - all calculation
scripts initiate; or
False - only
pending calculation
scripts initiate.
Designercalculat
eobject controls
whether a form filler
can override a field’s
calculated value.
execCalculate
Alternatively, you
can use the
execCalculate
method for each
object for which you
want to force a
recalculation.
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
Comments
createTemplate
No
None
Designer forms do
not have an
equivalent to the
concept of an
Acrobat template.
You must use
subform objects in
Designer.
deletePages
No
None
instanceManager
In Designer, you can
use the
instanceManage
robject to remove
the subform object
that represents a page
of your form.
For more
information, see
Addand remove
subform instances
using scripting.
embedDocAsDataObje
ct
Yes
None
encryptForRecipien
ts
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.exp
ortData()
exportData
The
exportDatameth
od exports an XML
or XDP file instead of
an FDF file.
129
JavaScript in Acrobat
130
Designer
support
JavaScript-equiva
lent in Designer
exportAsXFDF
No
xfa.host.exp
ortData()
exportDataObject
Yes
None
exportXFAData
No
xfa.host.exp
ortData()
extractPages
No
None
flattenPages
No
None
getAnnot
Yes
None
getAnnots
Yes
None
getDataObjectConte
nts
Yes
None
getField("FieldNam
e")
Yes
xfa.resolveN
ode
("FieldName"
)
getLegalWarnings
Yes
None
getLinks
No
None
getNthFieldName
Yes
You must loop
through all
objects with a
similar class name
until you reach
thenthoccurrenc
e.
getNthTemplate
No
None
Comments
exportData
The
exportDatameth
od exports an XML
or XDP file instead of
an FDF file.
exportData
The
exportDatameth
od exports an XML
or XDP file instead of
an FDF file.
resolveNode
The
resolveNodemet
hod accesses the
specified object in
the source XML of
the form.
className
See the
classNamepropert
y.
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
getOCGs
Yes
None
getOCGOrder
Yes
None
getPageBox
Yes
None
getPageLabel
Yes
None
getPageNthWord
Yes
None
getPageNthWordQuad
s
Yes
None
getPageNumWords
Yes
None
getPageRotation
Yes
None
getPrintParams
Yes
None
getTemplate
No
None
getURL
Yes
xfa.host.got
oURL(
"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.imp
ortData
("filename.x
dp");
insertPages
No
None
mailDoc
Yes
None
mailForm
No
None
Comments
See the
gotoURLmethod.
gotoURL
See the
importDatameth
od.
importData
131
JavaScript in Acrobat
132
Designer
support
JavaScript-equiva
lent in Designer
movePage
No
None
newPage
No
None
openDataObject
Yes
None
print
Yes
xfa.host.pri
nt();
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.res
etData()
or
xfa.event.re
set()
Comments
See the
printmethod.
print
The
resetDatamethod
resets all field values
on a form to the
default values. The
resetmethod
resets all properties
within the event
model.
resetData
reset
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
Comments
saveAs
Yes
None
spawnPageFromTempl
ate
No
None
setAction
No
None
setPageLabel
Yes
None
setPageRotation
No
None
setPageTabOrder
No
None
setScript
No
None
submitForm
Yes
Use one of the
submit button
objects in
Designer.
change
Yes
xfa.event.ch
ange
change
See the change
property.
targetName
Yes
xfa.event.ta
rget
target
See the target
property.
No
None
In Designer, the file
must be saved at the
application level.
These scripts are
examples of saving at
the application level:
app.executeMen
uItem
("SaveAs");
or
var myDoc =
event.target;
myDoc.saveAs()
;
In Designer, select
Edit > Tab Order to
set the tab order.
eventobject properties
fieldobject properties
comb
133
JavaScript in Acrobat
134
Designer
support
JavaScript-equiva
lent in Designer
Comments
charLimit
No
this.value.#
text.maxChar
s
In forms that have a
fixed layout,
character limit can
be set in the
Designer workspace.
You can set fields on
forms whose layout
expands to
accommodate all
data.
maxChars
display =
display.noView
No
See Changingthe
presence of a form
design object.
presence
You can also set the
presenceproperty
in the Designer
workspace.
You cannot use
theprePrintevent
to change the
presence of an object
prior to printing.
display =
display.noPrint
No
See Changingthe
presence of a form
design object.
presence
You can also set the
presenceproperty
in the Designer
workspace.
You cannot use
theprePrint event
to change the
presence of an object
prior to printing.
defaultValue
No
None
Set the default field
value in the Designer
workspace.
exportValues
No
None
Set the export value
in the Designer
workspace.
fillColor
No
xfa.form.For
m1.
NumericField
1.fillColor
fillColor
See the
fillColorpropert
y.
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
Comments
hidden
No
this.presenc
e =
"invisible"
this.
presence =
"visible"
presence
You can also set the
presenceproperty
in the Designer
workspace.
multiline
No
this.ui.text
Edit.multiLi
ne = "1";
multiLine
See the
multiLinepropert
y.
password
No
None
Designer contains a
Password Field that
you can use for
passwords on a form.
page
No
None
Not applicable for
Designer forms.
print
No
this.relevan
t =
"-print";
relevant
See the
relevantproperty.
radiosInUnison
No
None
Grouped radio
buttons in Designer
are mutually
exclusive by default.
rect
Yes
You can get the
height and width
of a Designer
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;
h, x, y
See the h,w,x,
andyproperties.
135
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
Comments
required
No
this.mandato
ry =
"error";
or
this.validat
e.nullTest =
"error";
mandatory, nullTest
See the
mandatoryand
nullTestpropertie
s.
textColor
No
this.fontCol
or
fontColor
See
thefontColorpro
perty.
textSize
No
this.font.si
ze
size
See the
sizeproperty.
textFont
No
this.font.ty
peface
typeface
See the
typefaceproperty.
value
No
this.rawValu
e
rawValue
See the
rawValueproperty.
value
Designer fields have
a valueproperty; it
is not the equivalent
of the Acrobat
value property.
clearItems
No
DropDownList
1.clearItems
();
clearItems
The
clearItemsmeth
od only applies to
Drop-down List and
List Box objects in
Designer.
deleteItemAt
No
None
getItemAt
No
None
insertItemAt
No
DropDownList
1.addItem
.....)
fieldobject methods
136
addItem
See the
addItemmethod.
JavaScript in Acrobat
Designer
support
JavaScript-equiva
lent in Designer
Comments
rawValue
See the
rawValueproperty.
isBoxChecked
No
if(CheckBox1
.rawValue ==
1)....
isDefaultChecked
No
None
setAction
No
None
Not applicable for
Designer forms.
setFocus
Yes
xfa.host.set
Focus
("TextField1
.somExpressi
on")
setFocus
The
setFocusmethod
requires that the
specified object have
a unique name with
respect to other
objects on your form.
setItems
No
None
setLock
Yes
None
signatureGetModifi
cations
Yes
None
signatureGetSeedVa
lue
Yes
None
signatureInfo
Yes
None
signatureSetSeedVa
lue
Yes
None
signatureSign
Yes
None
signatureValidate
Yes
None
searchobject method
137
JavaScript in Acrobat
search.query("<you
r text>");
Designer
support
JavaScript-equiva
lent in Designer
Yes
None
Yes
None
SOAPobject method
All properties and methods
RELATED LINKS:
Working with the Event Model
138
Comments
The “..” (double
period) FormCalc
shortcut syntax
allows you to search
for objects within the
XML Form Object
Model.
For more
information, see
FormCalc
referencesyntax
shortcuts.
Examples of Common Scripting Tasks
The scripting examples demonstrate quick and simple techniques that you can apply to your own
work.
For more examples and ideas, visit the DeveloperCenter.
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.
In this example, clicking a button changes the background color of an associated object.
To manipulate the background color of objects at run time, you must save your form as an
Acrobat Dynamic XML Form file.
NOTE:
To see this scripting example and others, visit the DeveloperCenter.
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:
139
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 expressions, 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";
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.
140
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. For information, see Buildingactions in
forms
In this example, all form objects are showing in the form.
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.
141
To hide and show objects at run time, you must save your form as an Acrobat Dynamic PDF
Form file.
NOTE:
To see this scripting example and others, visit visit the DeveloperCenter.
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; 
}
142
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;
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
break; 
case 'Hidden (Exclude from Layout)':
Subform1.nodes.item(nCount).presence
break; 
default: 
Subform1.nodes.item(nCount).presence
break; 
} 
} 
}
= "invisible"; 

= "hidden"; 
= "visible"; 
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;
143
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
break; 
case 'Hidden (Exclude from Layout)':
Subform1.nodes.item(nCount).presence
break; 
case 'Visible (but Don\'t Print)': 
Subform1.nodes.item(nCount).presence
Subform1.nodes.item(nCount).relevant
break; 
case 'Invisible (but Print Anyway)':
Subform1.nodes.item(nCount).presence
Subform1.nodes.item(nCount).relevant
break; 
default: 
Subform1.nodes.item(nCount).presence
break; 
} 
} 
}
= "invisible"; 

= "hidden"; 
= "visible"; 
= "-print"; 

= "invisible"; 
= "+print"; 
= "visible"; 
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();
144
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.
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
enter
Script
// 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); }
145
Event
exit
Script
// 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); }
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.
To alter the visual properties of objects on the client, you must save your form as an Acrobat
Dynamic PDF Form file.
NOTE:
In this example, the check boxes do not have unique object names; therefore, Designer 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 visit the DeveloperCenter.
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"; 
146
TextField.y = "3.5in"; 
} 
else { 
TextField.x = "1in"; 
TextField.y = "3in"; 
}
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 =
147
"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) 
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";
148
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.
149
if (CheckBox14.rawValue == true) 
xfa.resolveNode("TextField.ui.#textEdit.border.edge").stroke = "solid"; 
else 
xfa.resolveNode("TextField.ui.#textEdit.border.edge").stroke = "lowered";
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.
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.
NOTE:
150
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 visit the DeveloperCenter.
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;
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.
151
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.
To see this scripting example and others, visit the visit the DeveloperCenter.
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.
152
To see this scripting example and others, visit the DeveloperCenter.
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.
153
To see this scripting example and others, visit tvisit the DeveloperCenter.
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:
154
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.
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 tvisit the DeveloperCenter.
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:
155
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:
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:
156
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"; 
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 {
157
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.
In this example, the form filler can click the Clear button to reset the field values.
To see this scripting example and others, visit visit the DeveloperCenter.
158
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 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.
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.
NOTE:
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
ObjectName.relevant
JavaScript
ObjectName.presence
ObjectName.relevant
= "visible"
= "-print"
= "visible";
= "-print";
159
Presence setting
Visible (Print Only)
Reference syntax
FormCalc
ObjectName.presence
ObjectName.relevant
JavaScript
ObjectName.presence
ObjectName.relevant
= "visible"
= "+print"
= "visible";
= "+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.
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.
160
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);
161
You can also write this script by using the underscore (_) notation to reference the min property of
the instance manager, as shown here:
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.
162
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.
NOTE:
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); 
}
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:
163
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);
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.
164
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 Help.
NOTE:
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); 
}
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.
165
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 { 
166
xfa.host.messageBox("You have reached the maximum number of items allowed.",
"Combining Instance Manager Concepts", 1); 
}
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.
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.
NOTE:
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 
167
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;
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); 
}
168

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project