XFA Specification
Chapter 12, User Experience
Widgets
351
Data Associated with Choice List Selections
A choice list element may use the data displayed in the choice list widget as the value associated with the
selection, as does
Example 12.1.
Alternatively, a choice list element may define values associated with a
selection, as shown in
Example 12.2.
Example 12.2 Choice list that associates hidden data values with selections
<field >
<ui>
<choiceList … />
</ui>
<items >
<text>apples</text>
<text>bananas</text>
<text>pears</text>
</items>
<items save="1" presence="hidden">
<text>0</text>
<text>1</text>
<text>2</text>
</items>
</field>
The non-hidden items ("apples", "bananas", and "pears") appear to the user as possible choices and the
hidden items ("0", "1", and "2") are used for data values. The association between non-hidden items and
hidden ones is positional. For example, if the user selects "apples", the data value for the field is "0".
When to Update the XFA Data DOM
The choice list element includes an attribute (
commitOn
) that allows the widget to specify whether the
data selected in the choice list should be propagated to the XFA Data DOM as soon as the selection is
made (
commitOn="select"
)or after focus shifts to another field (
commitOn="exit"
). The former is
the default value.
Note:
Having a choice list commit data as soon as selections are made may be important in forms that
contain non-XFA interactive features, such as Acrobat annotations or hypertext links. People filling
out such forms may erroneously believe that selecting an item from a choice list followed by
clicking a non-XFA interactive feature is the same as exiting the check list. In fact, the check list
remains the field in focus.
Date/Time Editing Widget
The date-time editing widget (
dateTimeEdit
User Selects a Field That Has Date-Time Edit Widget
When the user selects a field or tabs into a field that has a date-time editing widget, the widget displays
the field’s data using the field’s ui picture clause if present. If such a picture clause is not present, the
widget displays the canonical format of the data. (“Canonical