list

Creates a list box from which users can make selections from a list or trigger actions such as enclosing a file or submitting the form.

Available options

acclabel, active, bgcolor, border, borderinfo, focused, fontcolor, fontinfo, format, group, help, itemlocation, itemnext, itemprevious, keypress, label, labelbgcolor, labelborder, labelfontcolor, labelfontinfo, mouseover, next, previous, printbgcolor, printlabelbgcolor, printfontcolor, printlabelfontcolor, printvisible, readonly, size, suppresslabel, value, visible, xformsenabled, xformsreadonly, xformsrequired, xformsvalid, xforms:select, xforms:select1

Examples

This is an example of a list that allows the user to select the gender of a patient. The example shows a fragment of an XForms instance and an XFDL list item, both of which are inside the same form. The XForms fragment contains an empty gender element. The gender element remains empty until the user makes a selection from the list.

<xforms:instance id="Patient">
   <record xmlns="">
      <patient>
         <name>Jane Doe</name>
         <gender></gender> <!-- empty until a selection is made, then F or M -->
         ...
      </patient>
   </record>
</xforms:instance>
...
<list sid="Gender">
   <xforms:select1 ref="patient/gender" appearance="compact">
      <xforms:label>Patient Gender</xforms:label>
      <xforms:item>
         <xforms:label>Female</xforms:label>
         <xforms:value>F</xforms:value>
      </xforms:item>
      <xforms:item>
         <xforms:label>Male</xforms:label>
         <xforms:value>M</xforms:value>
      </xforms:item>
   </xforms:select1>
</list>

The list can also be populated with data from an XForms instance, as follows:

...
<xforms:instance id="Patient">
   <record xmlns="">
      <patient>
         <name>Jane Doe</name>
         <gender></gender> <!-- empty until a selection is made, then F or M -->
         ...
      </patient>
   </record>
</xforms:instance>
...
<xforms:instance id="Genders">
   <genders xmlns="">
      <gender label="Female" code="F"/>
      <gender label="Male" code="M"/>
   </genders>
</xforms:instance>
...
<list sid="Gender">
   <xforms:select1 ref="patient/gender" appearance="compact">
      <xforms:label>Patient Gender</xforms:label>
      <xforms:itemset nodeset="instance('Genders')/gender">
         <xforms:label ref="@label"/>
         <xforms:value ref="@code"/>
      </xforms:itemset>
   </xforms:select1>
</list>

This allows you to dynamically update the list by updating the <xforms:instance id="Genders"> element with Web service results obtained by an <xforms:submission> or by XForms actions such as <xforms:insert> and <xforms:delete>.

For examples of list entries that trigger actions, see the XFDL cell item.

Usage details

Use of the non-XForms version of this item is deprecated because it does not work when placed in a pane or table. Form authors are encouraged to use this item with its XForms element even when not placed in a pane or table in order to maximize form maintainability.
The list displays its label above the item, and as many choices as its size allows.
The list of choices is generated from the <xforms:label> strings obtained from the <xforms:item> elements or from the <xforms:itemset> element.
You must use appearance="compact" in the <xforms:select1> and <xforms:select> elements.
To get the value of a list when using <xforms:select1> or <xforms:select>, dereference it in the following manner:
```
page_sid.list_sid.value
```
For example:
```
compute="PAGE1.Gender.value"
```
When cell items are used instead of <xforms:select1> or <xforms:select>, the value of the list is empty unless the selected cell is a select type (the default), in which case you can obtain the value of the list by using the dereference operator as follows:
```
page_sid.list_sid.value->value
```
Similarly, to obtain the <label> text of the selected cell:
```
page_sid.list_sid.value->label
```
Similarly, to obtain the sid of the selected cell:
```
page_sid.list_sid.value
```
When cell items are used, the <value> option will contain one of the following:
- The item reference of the most recently chosen cell, if the cell was of type <select>.
- Nothing, if the most recently chosen cell was of any type other than <select>.
When setting the size option of a list, the height and width of the list will be based on the average character size for the font in use (set with the fontinfo option).
A vertical scroll bar will appear with the list if the number of cells is greater than the height (defined with the size option) of the list.
When a format option is applied to a list, the formatting will be applied to the value of each cell linked to the list. Those cells that fail the check will be flagged or filtered. Those cells that pass the check will have their value replaced with a formatted value. See the XFDL <format> option for more information.
If any two combobox, list, or popup items use the same set of cells, they must apply the same formatting.