Adobe Acrobat - Getting Started

Programming in Adobe Acrobat sucks and should be avoided at all costs. However, if you must, this page presents a few hints that will make your job easier.

Most of this data is based on trial and error. This page is the only reasonable documentation of this data that I know of.

General

Each object can have code attached to it. On the upper right hand side of the form is a Language comboBox, make sure it says JavaScript. (You can change the default under File / Form Properties... / Defaults / Default Language.) Also be sure that the code is set to Run At Client.

Your code is entered in the Script Editor (Window / Script Editor). The various events are selected via the Show comboBox. Events that have code attached to them are indicated with an asterisk. The procedure is to

Click on a form object (like a button)
Select the appropriate event
Write some code in the Script Editor

Your code will actually not do anything unless the form is dynamic. (The brain dead default is static. Come on, if you type code that fails with the current settings, this product should at least warn you.) This can be set on individual forms by selecting File / SaveAs... and setting the File Type. It appears to be the same as settingt File / Form Properties... / Defaults #### check this (version 8, not in version 7). I prefer using Tools / Configuration... / Defaults #### check this to set the Default File Type for all future projects.

Context Sensitive Help

When typing code a small amount of context sensitive help is available when you type a period after an object identifier ... a scrollable list of applicable properties is displayed. Unfortunately,

You must type a period to see the possible options: Once the list closes, there is no known way to reopen it except to delete the existing text and type another period.
You must not have any character other than a space after the period: Simply typing a period is not enough, you must first create a space before typing the period.
Must press enter or double click the get the value: Other languages automatically take the highlighted value when you type a period or a space.

Getting F1 Help

F1 help is NOT context sensitive - you will have to type in what you want. For example

Type messageBox in the Script Editor, place the cursor in the phrase, and press F1
LiveCycle Designer displays the help for the Script Editor
Now type messageBox in the index search box

The help gives the following as the only example.

$host.messageBox("Hello World");

It does not bother to say that $host works only when the Language is set to FormCalc.

Notice that the help window stays on top of what ever you are doing. There is no way to alt-tab back to the designer like in other programming environments. (This is a common problem with Adobe products.)

Copy and paste from the help text does not work with the short-cut keys - Ctrl-C or Ctrl-Ins. Instead, you must right click the selected text and select copy.

Hello World

The first thing you should learn is how to display a message since this will help you debug your code.

Add a button to a blank form
In the Script Editor's Show comboBox, select click

Add either of the following lines of code

app.alert("Hello World");
xfa.host.messageBox("Hello World");

Click the PDF Preview tab
Click the button - the dialog box should display

When the JavaScript interpreter encounters an error, it aborts the code in that method - the rest of the code after the error is not executed. Placing several messageBox commands in your code is one way to locate the bad code. It is also a good way to determine which events are being called ... and the order they are called in.

Comments

The comments follow c-syntax

// single line comment
someCode ;  // end of line comment

/*

  block comment

*/

Referencing Objects

To create a reference to an object

Click in the code edit area
Hold down the Ctrl key
Click a component in the form

Note: In my opinion, this is the type of information that should be presented right up front. Instead, I found it on page 148 of some book.

While this is a useful shortcut, be careful - when you type a period after a reference of this type you will NOT be shown a context sensitive list of available properties. To get that, you must remove the reference from the double quotes. Clicking an object with the control key down gives you one of the following (depending on which language is selected)

form1.#subform[0].CheckBox1                      // When the language is FormCalc

xfa.resolveNode("form1.#subform[0].CheckBox1")   // When the language is JavaScript

Unfortunately, That is of limited value when JavaScript is selected because you do not get the correct context sensitive help when a period is typed. The trick is to get rid of the function call.

xfa.resolveNode("form1.#subform[0].CheckBox2").rawValue = 1;  // This works
form1.#subform[0].CheckBox2.rawValue = 1;                     // This fails

The problem with the first version is that the context sensitive help doen not include rawValue.
The problem with the second version is that #subform[0] is not understood.

The solution is to name the Subform. To do this

Click on untitled Subform in the Hierarchy tree.
Add a name in the Object window.

the following code works and provides context sensitive help

form1.main.CheckBox2.rawValue = 1;

Note that some default names begin with '#' and that these require xfa.resolveNode() to be used. In addition there can be several instances of a specific subform, each identified with a unique number like '[0]'. These also require xfa.resolveNode(). However, when there is only one instance, a named reference can be used, as shown above.

Property or Object

Even when using the documentation, it is never clear whether you are accessing a property or another object. The simplest way to determine this is to keep typing periods until there are no more popups showing possible options. If you do make a mistake of treating an object as a property, you may see a message similar to this.

Warning:[object XFAObject]

This displays the error

app.alert(xfa.resolveNode("form1.main.CheckBox2"));

and this does not

xfa.host.messageBox(xfa.resolveNode("form1.main.CheckBox2"));

Presence

Warning: Presence is broken in Adobe LiveCycle Designer 7 - setting it breaks RadioButtons.

Most component oriented languages provide visible and enabled properties to control the display of buttons, edit fields, and the like. Adobe decided to combine these properties in presence. As demonstrated in the 2 examples below, they completely messed this up in version 2.2

presence="visible \| invisible \| hidden"	xfa spec 2.2 - p 405 of 929
presence="visible \| inactive \| invisible \| hidden"	xfa spec 3.0 - p 533 of 1446

The result is that invisible causes some components to be rendered as shown but disabled. Specifically,

invisible hides the CheckBox's check mark and makes it unclickable
hidden has no effect on a CheckBox ... unless you first save the form as Dynamic PDF Form File (*.pdf)

Version 7

As I said above - Presence is broken in Adobe LiveCycle Designer 7 ... these are the details.

We have all seen forms where RadioButtons control which set of CheckBoxes work. In order to provide a visual indication, an attempt was made to place a light gray rectangle below each group of CheckBoxes ... when the RadioButtons were clicked, Rectangle1.presence was set as appropriate.

Unfortunately, this caused the selected RadioButton to automatically uncheck itself and additional attempts to click that RadioButton refused to run any code. To be clear - this is a major design problem in Acrobat.

Besides disabling a few CheckBoxes, the RadioButtons were supposed to hide and display subForms which contained various text fields. It turns out that presence also fails with subForms.

Under no conditions should presence be used in a version 7 form - it will have unpredictable results.

Summary

To be clear, RadioButtons work fine in Adobe LiveCycle Designer 8 but fail with version 7 ... and they fail with Adobe Reader (Acrobat) 7. Since there is no way to force users to load Acrobat Reader 8 (I refuse to describe this as an "upgrade" since it is obviously a "bug fix"), the only option is to not use any RadioButtons.

You won't believe this, CheckBoxes (work | also fail - still under investigation) with verion seven, only the RadioButtons fail.

Rectangle

Since there is no way to hide a rectangle, I tried to change its color. That simply does not work ... even though the help file says it will.

After several hours of testing, I determined that there is no way to modify a rectangle via code without crashing a version 7 form.

Program Debug

There is nothing anywhere about how to perform program debug. Although I discovered (by experimentation) that pressing F9 toggles a breakpoint in the code (puts a brown circle in the left hand margin next to the line of code the cursor was on), this actually does nothing.

This is really a very difficult language to debug.

References

References were hard to find until I started searching for form object model.

Adobe XML Form Object Model Reference - this is the primary language source (it took 2 days to find).

This Power Point Presentation provides links to additional documentation. Though this presentation is focused on converting from the old form standard to the new one, it does contain useful information.

Author: Robert Clemenzi - clemenzi@cpcug.org