xfa.host.openList(@object)
xfa.host.openList(@string) -- deprecated since XFA 2.6

where @object is a reference to the drop down list field and @string is the SOM expression of the drop down list field.

xfa.host.openList(myDropDownList); // set focus/show the drop list

The second form of the API has been deprecated since XFA 2.6 which means that since Designer 8.1, it is preferred to use the first form which takes a reference to the field rather than its SOM expression.

If you’re using Designer 8.0 or earlier, you can get the SOM expression of any field by using its somExpression property:

xfa.host.openList(ddlInDesigner71.somExpression)

This works in both JavaScript and FormCalc with the same syntax.

Now if only there was a way to programmatically show the drop calendar of a date/time field…

My friend Angie Okamoto (Easel Solutions) was the one who originally pointed this out to me. It’s incredibly useful, especially when you’re switching between various preview data files (or options like interactive vs non-interactive), because it loads the dialog and activates the Preview tab in a single step. This saves both mouse travel time and one click which adds-up to a lot, if you do this frequently.

Right-click on the PDF Preview tab to get the context menu:

Choose “Form Properties” and you’re right on the Preview tab:

Another option is to set a Shortcut Key for the Form Properties dialog, though this won’t auto-select the Preview tab (but still saves some mouse travel and a couple of clicks). You can do this via the “Tools > Keyboard Shortcuts” dialog:

Unfortunately, I don’t recall what version of Designer introduced the PDF Preview tab’s context menu nor which one added Keyboard Shortcuts but I think both should be available since version 8.0.

When editing the contents of a text object, pressing the [Enter] key will produce a paragraph break which means that any Above and/or Below Spacing you have specified will come into effect, amongst other paragraph formatting-related properties. Under the hood, the effect is the insertion of a “new line” character (\n) in a plain text object or a new <p> tag in a rich (XHTML) text object.

Sometimes, however, you need to break a line without producing a new paragraph. For example, you might have a long URL to insert and, given its position within the contents, it ends-up being broken onto another line and you would prefer to keep it on a single line, yet part of the same paragraph. To do this, use the [Shift + Enter] keyboard sequence. The result is a “soft” break to another line without moving to a new paragraph. Under the hood, this translates into the insertion of a U+2029 Unicode break character in plain text or a <br> tag in rich (XHTML) text.

Those of you using a version of Designer which precedes the 8.2.1 release should note that when using [Shift + Enter] in a plain text object, the contents of the object gets converted into rich text since previous versions of Designer would always use the <br> tag to denote a line break. Designer 8.2.1 coincided with the release of Acrobat/Reader 9.0 which provided improvements to the Text Engine in order to support the plain text U+2029 Unicode break character.

Line Breaks in Acrobat/Reader

What I describe above relates to the authoring experience in Designer. Inserting line breaks (as opposed to paragraph breaks) while filling a form in Acrobat/Reader is different. John Brinkman explains the “why and how” in this post.

Sample Form

Download Sample [pdf]

I have included a sample for that demonstrates the different types of breaks in both plain and rich text objects. I also included a text field that has a multi-line rich text caption (the contents of the rich text object) and a multi-line default value (the contents of the plain text object), both using paragraph and line breaks. (If you’re wondering how I got those values into the caption and default value properties, I used good old Copy & Paste in both cases.)

Minimum Sample Requirements: I authored this sample using Designer 8.2.1.2 and Acrobat 9.3. It should work back to Acrobat 9.0. I’m unsure of the results in earlier versions of Designer and Acrobat due to the use of the U+2029 character in plain text.

For example, say you have a simple form with a text field and a numeric field. The following statement will output the form’s data to the JavaScript Console in Acrobat:

console.println(xfa.datasets.data.saveXML());

The result, however, isn’t very readable:

<?xml version="1.0" encoding="UTF-8"?>
<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
><form1
><TextField1
>asdf</TextField1
><NumericField1
>1234</NumericField1
></form1
></xfa:data
>

Though I had been using saveXML() for quite some time, I hadn’t realized that it actually takes an optional parameter, a string with a value of “pretty”, that results in much nicer output.

console.println(xfa.datasets.data.saveXML('pretty'));

results in the following pretty/readable output:

<?xml version="1.0" encoding="UTF-8"?>
<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
   <form1>
      <TextField1>asdf</TextField1>
      <NumericField1>1234</NumericField1>
   </form1>
</xfa:data>

One other nice thing about console.println() for outputting debug information to the JavaScript Console in Acrobat is that these strings are also output to the Flash Log when you run form guides generated with LiveCycle ES Update 1 (8.2.1) using the Flash Debug Player. (The 3rd part of my MAX 2008 Tutorial series has details on how to set this up under the “Flash Log and Debug Players” section.)

The default setting is “Normal” which means that all new subforms you insert from the Object Library with have their “Object palette > Binding tab > Default Binding property” set to “Normal” which means implicit binding using the subform’s name.

Setting this to “None” will result in all new subforms having a default binding of “None” which means they don’t participate in data binding by default. Since subforms are often needed purely for form layout, I find it’s safer to use this setting because I know inserting new subforms will not affect any bindings I have already setup in my form. (While it’s true that unnamed subforms don’t participate in data binding, I always name my subforms for clarity and scripting purposes so setting the binding to “None” ensures they don’t mess with data binding unless I want them to.)