xforms:select (options)

Sets the choices that are displayed by a checkgroup or list when the user can select one or more of the choices. When the form is processed, an individual check or cell item is automatically generated to represent each choice.

Syntax

The xforms:select option has two different syntaxes, depending on whether the choices are included in the option itself, or whether the choices are included in the data model and linked by the option.

If you want to include the choices in the option itself, use the following syntax:

   <xforms:select single_node_binding appearance="style">
      <xforms:label>label text</xforms:label>
      <xforms:item1>
         <xforms:label>label for choice</xforms:label>
         <xforms:value>value for choice</xforms:value>
         <xforms:extension>XFDL Options</xforms:extension>
      </xforms:item1>
      ...
      <xforms:itemn>
         ...
      <xforms:itemn>
      Alert Setting
      Hint Setting
      Help Setting
   </xforms:select>
Note: There can be any number of xforms:item elements.
Table 1. xforms select parameters
Parameter Type Description
single node binding string see Single node binding.
style string sets to one of the following values:
  • full for a checkgroup
  • compact for a list item

Default: compact.
label text string sets the text for a label that is displayed at the top of the checkgroup. Leave this blank to display no label.

If the item also has a label option, it will override this setting.
label for choice string sets the text that is displayed for the choice.
value for choice string sets the value that is stored if the user selects this choice.
XFDL Options XFDL options adds specific XFDL options to the item represented by the choice. For example, you might want to add a type option to the choices in a list, so that the cells that are generated by those choices trigger actions.
Hint, Help Setting metadata see Metadata sub-options.

If you want to include the choices in the data model, use the following syntax:

   <xforms:select single_node_binding appearance="full">
      <xforms:label>label text</xforms:label>
      <xforms:itemset nodeset="XPath to choices">
         <xforms:label ref="XPath to label text"/>
         <xforms:value ref="."></xforms:value>
         <xforms:extension>XFDL Options</xforms:extension>
      </xforms:itemset>
      Hint Setting
      Help Setting
      Alert Setting
   </xforms:select>
Table 2. available choices to add to the data model
Parameter Type Description
single node binding string see Single node binding.
label text string sets the text for a label that is displayed at the top of the checkgroup.

Leave this blank to display no label.
XPath to choices string an XPath reference to the elements in the data model that provide the choices. This defines the set of item’s that the checkgroup or list displays as choices. This reference is relative to the XPath to element reference.

For example, your data model may contain the following elements that represent the choices for your item:

   <choice show="US Dollars">
      USD</choice>
   <choice show="CDN Dollars">
      CDN</choice>
   <choice show="Euros">
      Euro</choice>

In this case, you would reference those choices as:

   choice
XPath to label text string an XPath reference to the label text for each choice. This text is included in your data model as attributes on the data elements that contain your choices. This reference is relative to the XPath to choices reference.

For example, your data model may contain the following elements that represent the choices for your checkgroup:

   <choice show="US Dollars">
      USD</choice>
   <choice show="CDN Dollars">
      CDN</choice>
   <choice show="Euros">
      Euro</choice>

In this case, your would reference the show attributes that contain the text that describes that element, as shown:

   @show
XFDL Options XFDL options adds specific XFDL options to all items represented by the itemset. For example, if you are creating a checkgroup, you might want to set the itemlocation for all items in the set, so that they are spaced horizontally rather than vertically.
Hint, Help Setting metadata see Metadata sub-options.

Available in

checkgroup, list

Example

The following code creates a checkgroup with three choices: US Dollars, CDN Dollars, and Euro. The choices themselves are defined within the xforms:select option.

   <checkgroup sid="currency">
      <xforms:select ref="currency" appearance="full">
         <xforms:label
            >Select the currencies you accept:</xforms:label>
         <xforms:item>
            <xforms:label>US Dollars</xforms:label>
            <xforms:value>USD</xforms:value>
         </xforms:item>
         <xforms:item>
            <xforms:label>CDN Dollars</xforms:label>
            <xforms:value>CDN</xforms:value>
         </xforms:item>
         <xforms:item>
            <xforms:label>Euro</xforms:label>
            <xforms:value>Euro</xforms:value>
         </xforms:item>
      </xforms:select>
   </checkgroup>

Alternatively, you could create the choices in your data model as follows:

   <xforms:instance xmlns="" id="currency">
      <data>
         <currency/>
         <choice show="US Dollars">USD</choice>
         <choice show="CDN Dollars">CDN</choice>
         <choice show="Euros">Euro</choice>
      </data>
   </xforms:instance>

In this case, you would use the xforms:select option to link to those choices, as illustrated by the following checkgroup:

   <checkgroup sid="currency">
      <xforms:select ref="currency" appearance="full">
         <xforms:label
            >Select the currencies you accept:</xforms:label>
         <xforms:itemset nodeset="instance('currency')/choice">
            <xforms:label ref="@show"></xforms:label>
            <xforms:value ref="."></xforms:value>
         </xforms:itemset>
      </xforms:select>
   </checkgroup>

Usage details

  1. The single node binding for the xforms:select must refer to the same model as the single node bindings for the choices within the xforms:select.
  2. To create a checkgroup or list item from which the user can select only one choice, use the xforms:select1 option.
  3. The choices available in a list are equivalent to cells of type select. If you want a choice to perform a different action use the xforms:extension to set a different type. For example, the following xforms:item is set to type link: 
       <xforms:item>
      <xforms:label>US Dollars</xforms:label>
      <xforms:value>USD</xforms:value>
      <xforms:extension>
         <type>link</type>
         <url>http://www.ibm.myserver.com/mypage.htm</url>
      </xforms:extension>
   </xforms:item>
  4. If your xforms:select contains both an xforms:itemset and one or more xforms:item elements, the xforms:itemset is used and the individual xforms:item elements are ignored.
  5. The single node binding in the xforms:select option creates a link between the value option for the containing item and the bound element in the data model, so that they share data. When the user makes a selection, the xforms:value of that selection is stored in the XFDL value of the item containing the xforms:select and in the data node bound to the xforms:select.
  6. If the user makes multiple selections, those choices are stored as a space delimited list. The selected items are listed by their build order in the form. Because this list is space delimited, the choices themselves cannot contain spaces.
  7. To store the value of each selection in its own data element, use the xforms:select and xforms:deselect events. For more information, refer to XForms actions.
  8. The item set (determined by the xforms:item elements or the xforms:itemset element) may be empty if the bound nodes contain no data, or if the bound nodes are not relevant. In either case, the containing item is displayed without any choices. For example, a checkgroup would be displayed without any checks in it.
  9. Checkgroup and radiogroup items are arranged vertically by default (that is, each choice appears immediately below the previous choice). To arrange checkgroup or radiogroup items in another manner, use the xforms:extension to add an itemlocation to each item in the group. For example, you might set the items to appear one after another horizontally with the following itemlocation: 
       <itemlocation>
      <after compute="itemprevious"/>
   </itemlocation>
  10. To set the choices in a list to perform particular actions, such as a save or submit, use the xforms:extension to add a type option to each <xforms:item> element. For example, you might create the following items in your list: 
       <xforms:item>
      <xforms:label>Save</xforms:label>
      <xforms:value>Save</xforms:value>
      <xforms:extension>
         <type>saveas</type>
      </xforms:extension>
   </xforms:item>
   <xforms:item>
      <xforms:label>Submit</xforms:label>
      <xforms:value>Submit</xforms:value>
      <xforms:extension>
         <type>submit</type>
      </xforms:extension>
   </xforms:item>
  11. The value option overrides the xforms:value of the listed choices. This is useful when working with list items. A list displays the xforms:label of a choice until it is selected, at which point it displays the xforms:value of a choice. This means that you can set the value option to override the default xforms:value, which will change what is displayed when a choice is selected.

    For example, you might have a data model that sets a full text label for the choices, but uses an abbreviated value. The following instance shows this, using the show attribute to set the xforms:label and the contents of each element to set the xforms:value:

       <xforms:instance id="currency">
      <data>
         <choice show="US Dollars">USD</choice>
         <choice show="CDN Dollars">CDN</choice>
         <choice show="Euros">Euro</choice>
      </data>
   </xforms:instance>

    In this case, you might want to display the full text label even after a choice is selected. You can do this by using xforms:extension to add a value to each item in the set. You can then set the value to compute its contents to equal the label, which is populated with the full text description. The following sample shows this:

       <checkgroup sid="currency">
      <xforms:select ref="currency" appearance="full">
         <xforms:label
            >Select the currencies you accept:</xforms:label>
         <xforms:itemset nodeset="instance('currency')/choice">
            <xforms:label ref="@show"></xforms:label>
            <xforms:value ref="."></xforms:value>
            <xforms:extension>
               <value compute="label"/>
            </xforms:extension>
         </xforms:itemset>
      </xforms:select>
   </checkgroup>
  12. Any item with an xforms:select option can trigger XForms actions using the xforms-value-changed, xforms-select, or xforms-deselect events. For more information, refer to XForms event handlers.
Parent topic: XForms options