When I occasionally browse around some of the LiveCycle forums, I frequently see questions around how to populate a drop down list. I have put together a sample form that illustrates several different options.
Data Source
There are two basic sources for updating a drop down list definition: data binding or script. If the list contents are defined as part of your form data, and if they don't change during your form session, then use data binding. If the definitions are more fluid, then use script.
The preOpen Event
The most important take-away from this blog entry concerns what event to use for updating lists. I have seen customer forms that update list contents using change, exit, calculate, validate, mouseover, and enter events. However, the proper place to do it is in the preOpen event. The preOpen event fires when the user activates the control for the choice list. Think of it as the "just-in-time" option. If you try to maintain your list box definition from other events then often your script will update your list box contents too frequently.
The only reason for updating a choice list sooner than the preOpen event is if you need to assign a value to a list field. e.g. if your drop down list has a display value: "ONE" and a bound value: "1", then assigning
field.rawValue = 1; will cause the field to display "ONE". Obviously this works only if the field has up to date list contents. If you need your list contents updated more frequently, you should still put the list populating logic in the preOpen event, and use execEvent("preOpen") to populate the list from other contexts where it's needed.
The sample form has four choice lists that get populated from their preOpen event, using data found in form field values, JavaScript arrays and XML data.
Script Commands
There are two script methods for setting your list box contents:
field.addItem()
and
field.setItems().
The API: field.addItem() works in all versions of Reader. field.setItems() was introduced in Reader 9.0 and is much faster and more convenient. The sample form has script that illustrates how to use each method.
Binding to Data
I constructed some sample data (dogs.xml) that looks like this:
<dogs>
<category file="ugliest">
<rank>1</rank><dog>Chinese Crested</dog>
<rank>2</rank><dog>Pug</dog>
<rank>3</rank><dog>Shih Tzu</dog>
<rank>4</rank><dog>Standard Schnauzer</dog>
<rank>5</rank><dog>Chinese Shar Pei</dog>
<rank>6</rank><dog>Whippet</dog>
<rank>7</rank><dog>Dandie Dinmont Terrier</dog>
<rank>8</rank><dog>Japanese Chin</dog>
<rank>9</rank><dog>French Bulldog</dog>
<rank>10</rank><dog>Chihuahuas</dog>
</category>
<category file="dumbest">
...
</category>
<category file="comicBook">
...
</category>
<category file="smartest">
...
</category>
</dogs>
On my form I want two drop down lists: one with the names of the categories and a second that gets populated with the contents of the category. Since this XML is part of my data, I bound the category using these expressions:
The second list has a preOpen event that locates the category in the data, and then populates a second listbox from the category contents:
// Find the data group that corresponds to the category chosen
// in the Category fieldvar vDogs = xfa.datasets.data.dogs.category.all;
var vChoice = null;
var i;
for (i = 0; i < vDogs.length; i++) {
if (vDogs.item(i).file.value === Category.rawValue) {
vChoice = vDogs.item(i);
break;
}
}
if (vChoice !== null) {
// vChoice.dog.all is the equivalent of the
// SOM expression: "category.dog[*]"
var vDisplayValues = vChoice.dog.all;
var vBindValues = vChoice.rank.all;
for (i = 0; i < vDisplayValues.length; i++) {
this.addItem(vDisplayValues.item(i).value,
vBindValues.item(i).value);
}
}
Performance
Populating a list from data is very efficient. But populating large lists or many lists using addItem() can be slow.
The performance gains of setItems() over addItem() is substantial. If your form makes extensive use of choice lists or has choice lists with large contents, you will appreciate the improvements of setItems(). Of course, this option is available only in forms designed for Reader 9 or later.
Web Services
In some cases, the definition of the choice list may be held on a server. In this scenario, the best strategy is to add a WSDL connection to your form that retrieves the list contents. Have your list box bind its contents to the data retrieved via the SOAP call.
Away for a week
After I eat lots of turkey on the weekend (Canadian Thanksgiving), I'm spending next week trying to empty the job jar at home.
