Jeff Stanier recently posted an article on LiveCycle Product Blog announcing the availability of a utility for converting xForms into XFA forms for those who are currently using xForms but would like to "leverage Adobe’s presentation capabilities."

Check it out and let me know what you think!

---

Posted by Stefan Cameron on February 21st, 2007
Filed under General

---

Did you know that periods (.) are valid characters in XFA object names? On the surface, this may seem innocent but it’s really kind of strange when you think about it — especially when it comes to writing scripts: How would you access the properties or methods of an object if had a period in its name?

Consider a simple form with a button and a text field which is named "TheText.Field". Notice the period in the text field’s name. If you wanted to write a little line of script in the button’s Click event which set the text field’s value to some arbitrary text, you would not be able to write the following:

TheText.Field = "text" // FormCalc

It would produce an error because the script engine would think that you’re referencing an object named "Field" which is a child of a parent object named "TheText" when you’re actually trying to reference the "TheText.Field" object.

If XFA allows for periods in object names, there must be a way to access them correctly. To find the answer, one of the things you can do is a little test which exposes the text field’s SOM expression (say, in the text field’s Enter event):

xfa.host.messageBox($.somExpression) // FormCalc

Doing this for the text field would give the following result:

xfa[0].form[0].form1[0].#subform[0].TheText\.Field[0]

Notice the backslash which precedes the period in the "TheText.Field" name: Backslashes are used to escape period characters in XFA names in SOM expressions.

Knowing this important detail, you could change the earlier script to the following:

$.parent.resolveNode("TheText\.Field") = "text" // FormCalc

and everything would work just fine. The resolveNode method is necessary in this case since the script engine doesn’t support backslashes in statements in FormCalc (and neither in JavaScript for that matter).

Finally, don’t forget that backslashes in strings in JavaScript are used to escape other characters such as "\n" for a new line character. This means that when you write the object’s name in the resolveNode method call, be sure to escape the backslash itself in order to give the correct expression to the resolveNode method:

this.parent.resolveNode("TheText\\.Field").rawValue = "text"; // JavaScript

---

Posted by Stefan Cameron on February 14th, 2007
Filed under Scripting

---

Some of you may recall my tutorial on sorting lists at runtime which I posted last June. Oh how I wish I had waited until the release of Designer and Acrobat 8.0 in order to write it! With the new release of these two products comes a new API for list objects that would’ve significantly simplified things: Rather than having to know details about how list object items are represented in XFA (using an <items> node for item text values and an <items save="1"> node for item data values) and manipulating these nodes in script, I could’ve used methods such as getDisplayItem and getSaveItem.

New Properties

• length: Returns the number of items in the list object. This property is read-only.
• selectedIndex: Returns the zero-based index of the first-found item which is selected or -1 if the list has no selection. You may set this property in order to set a new selection in the list or set it to -1 in order to remove the selection entirely. Note that setting this property will first de-select any currently-selected items prior to applying the new selection.

New Methods

• bool getItemState(int index): Returns true (1 in FormCalc) if the list item specified by the zero-based index parameter is currently selected in the list.
• setItemState(int index, bool state): Add or remove a list item from the selection by specifying its zero-based index and true to select or false to de-select it (1 or 0, respectively, in FormCalc). Note that if the list object does not support multiple selection (drop down lists typically don’t), using this method will have the same effect as setting the selectedIndex property.
• string getDisplayItem(int index): Returns a list item’s text value (this pertains to the list’s <items> element in XFA) based on a zero-based index into the list.
• string getSaveItem(int index): Returns a list item’s data value (this pertains to the list’s <items save="1"> element in XFA) based on a zero-based index into the list.
• bool deleteItem(int index): Deletes the list item specified by a zero-based index and returns true (1 in FormCalc) to indicate that the item was effectively deleted.

Demo Form

In order to show-off this cool new API (available in both JavaScript and FormCalc), I designed a little form that uses all the new properties and methods. Play with it in Acrobat 8.0 and check out the script in Designer 8.0. I’m certain it’ll make your life a whole lot easier when it comes to scripting list boxes and drop down lists.

Download Sample [pdf]

Minimum Requirements: Designer 8.0, Acrobat 8.0.

Note that you must click away from the "List Box" object after you’ve set a selection since the list is set to commit its selection on exit (as is recommended when supporting multiple selection). You can specify this by setting the "Commit On" property on the Object palette’s Field tab to "Exit".

---

Posted by Stefan Cameron on February 1st, 2007
Filed under Scripting,Tutorials

---