Since the release of Designer ES 8.2 and now LiveCycle ES Update 1, the documentation page has been updated with all sorts of goodies related to Update 1, including the following Designer-related documentation:

• Scripting Reference (technical document about scripting your forms)
• Target Version Reference (if you want to know what features are compatible with specific PDF versions or if you’re using Designer ES 8.2 to build a form for users on Acrobat/Reader 7.x and you want to make sure they can use your form)
• Scripting Errors Reference (solutions to common scripting errors)
• FormCalc Reference (for those of you who like to use FormCalc instead of JavaScript, this reference includes previously-omitted information about various language constructs such as “while”, “for” and “for each” loops)

---

Posted by Stefan Cameron on July 21st, 2008
Filed under Designer, FormCalc, Scripting

---

The scenario

You have a compliant form that has sections for users to fill-in information. Because the form is compliant (i.e. its layout has received the “stamp of approval” and cannot change without another lengthy approval process), the sections cannot grow (they cannot expand-to-fit all of the text users may fill-in). To provide more space for users to add more text, you’ve provided an expandable “overflow” section at the end of form since expanding that section will not affect the portion of the form which has been approved.

The problem

You need to capture the text entered into the form using an interactive Form Guide which is not limited to the restrictions of the form’s approved layout. As such, the Form Guide will capture the text in a single field and you need that text to be entered into the PDF version of the form. If you put all the text into the appropriate section on the form, it won’t fit and the text will be cut-off (e.g. it will not print entirely and you will miss some of the important information).

You need some way to automatically split that text between the small section in the form and the overflow section at the end of the form. In other words, you need to ensure that only the text that can fit within the small form section is placed there and the rest is placed in the overflow section at the end.

In Designer 8.2, the content of fields can now be split between pages however in this case, you can’t use this feature because the small form section can’t be expanded (it’s fixed in size).

The solution

This is the problem Stephanie, Glenn and I were faced with on a recent customer visit. Stephanie took the time to put this into a sample form which provides the script we wrote to handle this task. It’s basically a mini text parser written in JavaScript that splits text between two fields with a fixed-width font (e.g. Courier New, Lucida Console, etc.).

---

Posted by Stefan Cameron on July 10th, 2008
Filed under Acrobat, Designer, Form Guides, Scripting, Tutorials

---

Here’s a quick observation you might find useful: The order in which form objects are initialized is “field and depth-first” according to the document order (the top-down order in which they appear in the Hierarchy palette in LiveCycle Designer). This means that fields inside a subform are initialized before the subform itself is initialized. When you think about it, it makes sense since this means that in a subform’s Initialize event, you always have access to properly-initialized child form objects. You can read more about event execution order in the LiveCycle Designer Scripting Basics document (page 24) as well as in the

XFA Spec (page 353 in version 2.7).

Say your form object hierarchy looked like this (in the Hierarchy palette in Designer):

The fields and subforms would get initialized in the following order:

To clarify, this is the order (note that text objects don’t get initialized just like squares, circles and images wouldn’t — image fields would, however):

0. DateTimeField1
1. TextField1
2. PasswordField1
3. Subform2
4. NumericField1
5. Subform1
6. CheckBox1

To demonstrate this, I’ve provided the form that contains the objects above. When you preview the form (or view it in your web browser) using Acrobat, use the JavaScript Console to see the output from the Initialize events of the various form objects to see the order of initialization.

Download Sample [pdf]

Minimum Requirements: I created this form in Designer 8.1.1 SP2 and tested it in Acrobat Pro 8.1.2.

---

Posted by Stefan Cameron on May 9th, 2008
Filed under Events, Scripting, Tutorials

---

Did you know that you can quickly set the background fill color of a field via script using the

fillColor

property? This can be very handy if you want to highlight a field for some reason. The property takes an RGB color value as a string: "255,0,0" would give a red fill.

What you may not realize is that fields actually have two areas: The "nominal extent" represents the entire field, including the caption, while the "content extent" represents only the data input portion of the field. There’s a difference between setting the fill color of one vs. the other.

The Nominal Extent Fill

When you set the fill color using the "fillColor" property, you’re setting the fill color of the nominal extent’s border property. It’s actually a shortcut:

TextField1.fillColor = "255,255,0"; // yellow

is equivalent to this:

TextField1.border.fill.color.value = "255,255,0";

Here’s a text field with no fill:

And here it is after setting its "fillColor" property to yellow:

(On a side note, you may notice that the field now has a border and you’re probably wondering where it came from. See this article for an explanation and what you need to do to get rid of it.)

The Content Extent Fill

So how do we set the fill color of the content extent without filling the entire field? The content extent’s fill color is specified within the field’s content extent (or "UI", in XFA terms) border and is accessed like this:

TextField1.ui.oneOfChild.border.fill.color.value = "0,200,0"; // green

(If you’re wondering what the "oneOfChild" property is, see this article.)

The result of the above line of script on the initial text field is as follows:

For example, you could use the content extent fill color as a way to communicate to someone that a field is disabled (by setting its content extent fill color to light gray (230,230,230)).

Finally, you can combine the two as follows (this being the combination of setting both the nominal and content extent fill colors):

---

Posted by Stefan Cameron on March 14th, 2008
Filed under Scripting, Tutorials

---

A common need in forms is to ask the user to choose between a set of options within a list, be it a radio button list, list box or drop down list. What’s more is that these lists often include an “other” option to let the user specify something more specific that isn’t included in the list. The trouble is, how do you ensure that the user fills-in the “other” field prior to submitting their form?

I thought it might be useful to provide a sample form which demonstrates how to build a list field which has an “other” option and clicking on the “other” option displays a field for entering the specific value and makes that field required — but only if the user chooses the “other” option. (You wouldn’t want the “other” field to be hidden and required or else the user would never be able to submit their form since Acrobat would prevent the submission on the premise that there’s an un-filled required field somewhere.)

“Other” Fields in Acrobat/Reader 8.1+

The first thing I did was create my sample form using Designer 8.1 and Acrobat 8.1. That was very easy and just as straight-forward as I expected it would be: One radio button list, one list box and one drop down list, each set to be required and with their own “other” item and script to show their respective “other” field (and make it mandatory) when their “other” item is selected and hide it (and make it optional) when their “other” item is de-selected. Add a submit button and Acrobat/Reader 8.1 automatically takes care of preventing the submission if any required field isn’t filled.

To keep things simple, each list field has script that detects when the user either selects the “other” item or an alternate item and sets the presence and mandatory properties of its “other” field to be visible/required or invisible/optional, respectively.

Download 8.1 sample [pdf]

Minimum requirements: Designer 8.1, Acrobat/Reader 8.1

“Other” Fields in Acrobat/Reader 8.0 or Earlier

Unfortunately, I didn’t have the same kind of experience getting this form to work in Acrobat/Reader 8.0 or earlier.

The first thing I did, since my 8.1 sample form doesn’t use any functionality only available as of Designer/Acrobat 8.1 (in fact, it uses XFA properties and script functions that have been available since Designer/Acrobat 7 and likely even earlier), I simply used Designer 8.1 to set my form’s Target Version to Acrobat/Reader 7.0.5 and figured I would open it in Acrobat 7.0.9 and all would be good. Well, that wasn’t the case.

Aside from Acrobat not respecting the “required” setting on the radio button list (which was expected since required radio button lists weren’t supported until Acrobat 8.0), I discovered a very strange behaviour in the list box where simply having a statement within its Change event that sets a field’s mandatory property to “error” will always result in that field being required, as far as Acrobat/Reader is concerned, even if the statement doesn’t appear ever to be executed on form initialization. The result is that selecting an item other than the “other” item in the list box and attempting to submit the form prompts Acrobat to cancel the submission because a required field isn’t filled. The problem is that the required field is the list box’s “other” field which is hidden from view because it isn’t supposed to be required. Finally, there was also another issue with list boxes that have Change event script: Their value is never committed to the Data DOM, which means that the list box always appears to have no value and that also prevents the user from being able to submit the form because the list box appears never to have been filled (even though an item is clearly selected).

So the are three problems with the 8.1 sample form when it’s running in versions of Acrobat/Reader prior to 8.1:

1. Although properly supported in Acrobat/Reader 8.0, radio button lists can’t be set to “required”;
2. List boxes with Change event script containing a statement which sets a field’s mandatory property to “error” results in that field always being “required” (this strange issue is resolved in Acrobat/Reader 8.1); and
3. List boxes with Change event script don’t commit their value to the Data DOM (this is also resolved in Acrobat/Reader 8.1).

Fortunately, issues #2 and #3 can be resolved fairly easily simply by not using the Change event. The only viable alternative I found was using the Exit event instead. (Note that in the Exit event, you have to use the list’s “rawValue” property to determine its value rather than using the “xfa.event.newText” property as in the original Change event script.)

Issue #1 (required radio button lists not supported) can also be resolved although it requires a little more work. One alternative is to use the “Two Button Submit” Technique I described on a previous post on Complex Validations, which is what I implemented in my 7.x sample form.

Download 7.x sample [pdf]

Minimum requirements: Designer 7.0, Acrobat/Reader 7.0

---

Posted by Stefan Cameron on August 7th, 2007
Filed under Acrobat, Bugs, Events, Scripting, Tutorials

---