I just discovered yet another (not so new) LiveCycle blog which I thought you might find useful: The LiveCycle Documentation Team’s blog already has a few useful posts on a variety of LiveCycle-related subjects. They plan to use it to provide product documentation updates and additional information between releases.
Target Version is a feature introduced in LiveCycle Designer 8.1 which alerts you to incompatibilities with various versions of Acrobat/Reader in your forms.
Whenever new versions of Acrobat and XFA are released, they introduce new features that previous versions don’t support. For example, the signature field’s “lock after signing” feature is only available as of Acrobat/Reader 8.0 and the hyperlink feature is only supported as of Acrobat/Reader 9.0. There are many other features that have similar version restrictions but how are you supposed to figure it out? When you’re designing your form, how can you be certain that your customers still using Reader 7.0.5 will be able to use it as you intended them to when you’re designing your form using the latest and greatest combination of Designer 8.2 and Acrobat 9.0?
That’s where Target Version becomes indispensable: By setting the “File > Form Properties > Defaults > Target Version” property to the version of Acrobat/Reader you want to target, you enable Designer to warn you when you use a feature that isn’t supported in that version. So if you target Acrobat/Reader 7.0.5 and you try to use hyperlinks, you’ll get a warning indicating that Acrobat/Reader 9.0+ is required to use hyperlinks.
To put this into perspective, Alex Kalaidjian, a developer on the LiveCycle Designer Team, has produced a short video tutorial demonstrating the usefulness of the Target Version feature.
This is something I get asked a lot so I thought I’d write a little tutorial on how to handle a selection change in a list object (drop down list or list box).
All XFA events have an object that represents properties about the event currently in execution:
xfa.eventThis object holds many interesting properties but the one that’s important here is the newText property which, for a list, contains the new selection.
It’s important to note that there are two types of list items: Ones that have text data only and ones that have both text and value data. By default, the Object palette creates lists with items that have text data only. On the Field tab, you can add/remove items and specify their text data while on the Binding tab, you can optionally set each item’s value data by checking the “Specify Item Values” box.
The xfa.event.newText property always returns the text data. You can access the value data associated with the new text data by using the list’s boundItem() method:
// get the value data associated with the new selected text data
var newValue = MyList.boundItem(xfa.event.newText);For single selection lists, you can therefore use the text data or get the associated value data for the new selection and do something from there. The following code sample gets the new selected value data in a list object’s Change event and changes the list’s background color accordingly:
var newValue = this.boundItem(xfa.event.newText);
switch (newValue)
{
case 1:
this.fillColor = "255,0,0"; // red
break;
case 2:
this.fillColor = "0,255,0"; // green
break;
case 3:
this.fillColor = "0,0,255"; // blue
break;
}List objects may also support a multiple selection of items. You can specify that the list supports multiple selection by setting the “Object palette > Field tab > Allow Multiple Selection” property but you cannot specify a default selection of multiple items using the Object palette (only a single default selection is supported though it still works for lists that allow multiple selections). You would have to use the list’s Initialize script to do that.
At runtime (e.g. in Acrobat/Reader), you may select multiple items in the list by using the Shift and Ctrl keyboard keys: Shift + Click will select all items from the last selected item to the item you click on and Ctrl + Click will add/remove individual (non-sequential) items to/from the selection.
Determining the selection in a multiple selection list is different from doing so in a single selection list because you have to deal with the fact that more than one item may be selected. There is also a difference in the event you must use in order to handle the change in selection: When you set the “Allow Multiple Selection” property, the “Object palette > Field tab > Commit On” property changed to allow only a setting of “Exit” (as of Designer 8.1; Designer 8.0 may have still allowed “Select” to be chosen however I recommend setting this property to “Exit” if you have the choice) which means that the change in selection — as far as the list is concerned — will only take place once the user exits the list (once they hit the Enter key, tab away or click away from the list) rather than immediately when they visually change the selection. The result is that you must handle the change in selection in the Exit Event rather than in the Change event as in single selection lists.
You can handle a change in single selection lists using the Exit event as well however for single selection lists, it’s usually preferable to handle the change immediately rather than once the user leaves the list. For multiple selection lists, the idea is that the user may click more than once to set the selection they want so you typically want to react to the change only once they’re done which is why the selection is only committed once the user exits the list.
Determining the set of selected items was really difficult leading up to Designer and Acrobat/Reader 8.0 when the new list object properties and methods were finally introduced. These new APIs make it much easier to deal with lists that contain multiple selections: Use the length property to iterate through the items, the getDisplayItem method to get the text data associated with an item, the getSaveItem method to get the value data associated with an item and the getItemState method to determine whether the item is selected or not.
Here’s our sample script from earlier that sets the background color of the list object after a change in the selection (in the list’s Change event) however this time the script is meant for the Exit event and the list supports multiple selection. The color values are combined if more than one is selected, producing more color combinations up to white (an RGB color value of “255,255,255”) then all 3 items are selected:
// array with 3 elements, all at zero initially
var rgb = new Array(0, 0, 0);
for (var i = 0; i < this.length; i++)
{
if (this.getItemState(i))
{
// item is selected
// item values are 1, 2 or 3 (1-based)
// array elements are 0, 1 or 2 (0-based)
rgb[this.getSaveItem(i) - 1] = 255;
}
}
// Array.toString() produces a comma-delimited string containing the
// values of the array elements so this will produce "255,0,255" if
// items 1 and 3 are selected.
this.fillColor = rgb.toString();If you give this a try, remember to create a list with 3 items (1, 2, 3) and place the script in the Exit event, not the Change event. Then remember to click away from the list once you’ve set the selection at runtime.
Setting a default selection of more than one item is unfortunately not something that Designer supports. To achieve this, you’ll need to set the list’s Initialize script to do the work. For example, to initialize a multiple selection list of 5 items where items 1, 4 and 5 are selected, you would do this (remember that list item indexes are 0-based, not 1-based) in the list’s Initialize event:
this.setItemState(0, true); // item 1
this.setItemState(3, true); // item 4
this.setItemState(4, true); // item 5To see this in action in what you might consider a more realistic example, my “What About the Other Field?” tutorial uses single selection lists that show an “other” field when their “other” item is selected.
John Brinkman, a colleague of mine at Adobe and the LiveCycle Forms Architect no less, has decided to start a new blog on form design. It looks like he will be concentrating on on best-practices relating to form design and scripts based on past experience with forms from various customers (in other words, based on real-world forms).
Hi first post relates to exclusion group-like functionality using any type (or combination) of fields in a subform where each field is treated as a mutually-exclusive radio button. Check it out, it works very nicely!
I noticed that Alex Kalaidjian, from the LiveCycle Designer Team, has posted another training video on Adobe’s LiveCycle DevNet. This time it’s on tab order, which is a great complement to my tab order article from the other day. Alex shows just how easy it is now to fix some common tab order issues with your forms using the new user interface for tab order available in Designer 8.2.
