combobox

Comboboxes act like a hybrid of a field and a popup.

Unopened, a combobox with a label occupies the same space as two labels, and a combobox without a label occupies the same space as a single label. After a user chooses a cell, the combobox closes (that is, returns to its unopened state).

If none of the cells are appropriate, the user can type other information into the combobox. When information is typed in, it is stored in the value option of the combobox. When a cell is selected, the value option stores the value of that cell, so unlike other list items (popup and list), dereferencing is not necessary.

A combobox's label appears above the combobox item.

Available options

acclabel, activated, 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, xformsrequired, xformsreadonly, xformsvalid, xforms:input, xforms:select1

Examples

This is an example of a combobox that allows the user to select the gender of a patient. The example shows a fragment of an XForms instance and an XFDL combobox 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 popup 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>
...
<combobox sid="Gender">
   <xforms:select1 ref="patient/gender" appearance="minimal">
      <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>
</combobox>

Clicking on the combobox opens a list that displays Female and Male. When the user selects one of the list items, the value is stored in the XForms model and the combobox displays the value. In the example, if the user selects Female, the text F is stored in the node patient/gender and the text F is displayed in the combobox.

The combobox 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>
...
<combobox sid="Gender">
   <xforms:select1 ref="patient/gender" appearance="minimal">
      <xforms:label>Patient Gender</xforms:label>
      <xforms:itemset nodeset="instance('Genders')/gender">
         <xforms:label ref="@label"/>
         <xforms:value ref="@code"/>
      </xforms:itemset>
   </xforms:select1>
</combobox>

This allows you to dynamically update the combobox 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.
When a combobox is activated, it displays a list that is generated from the <xforms:label> strings obtained from the <xforms:item> elements or from the <xforms:itemset> element. When cell items are used with the popup instead of <xforms:select1>, the list is generated from the cell labels.
You must use appearance="minimal" in the <xforms:select1> element.
To get the value of a combobox when using <xforms:select1>, dereference it in the following manner:
```
page_sid.popup_sid.value
```
For example:
```
compute="PAGE1.Gender.value"
```
When first viewed, a combobox will display its value. If no value is set, the combobox will be empty.
The label option sets the text displayed above the item, as with a field.
When a value is typed into a combobox (rather than selected from the list), the combobox's value is set to the typed value.
When setting the size option of a combobox, the height and width of the popup will be based on the average character size for the font in use (set with the fontinfo option).
If you set the readonly option to on, the combobox will refuse all input, although it will function normally otherwise and formulas will still be able to change the value.
To make a combobox that displays a calendar widget, create a combobox with no cells and give it a date format.
In Webform Server, comboboxes have type-ahead search functionality. For example, in a combobox containing the names of countries, you can type "ca" to immediately find "Cameroon" and other country names with these same starting letters. This function is not available in the Viewer.