Selection Controls

Single selection (select1)

Minimal appearance (dropdown)

Basic usage

<xf:select ref="selection" appearance="compact">
    <xf:label>Dropdown</xf:label>
    <xf:hint>Standard dropdown</xf:hint>:label>
    <xf:item>
        <xf:label>Cat</xf:label>
        <xf:value>cat</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Dog</xf:label>
        <xf:value>dog</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Bird</xf:label>
        <xf:value>bird</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Fish</xf:label>
        <xf:value>fish</xf:value>
    </xf:item>
</xf:select>

Appearance

Compact appearance (list box)

Basic usage

<xf:select1 ref="selection" appearance="compact">
    <xf:label>Single List Box</xf:label>
    <xf:hint>Standard single-selection list</xf:hint>:label>
    <xf:item>
        <xf:label>Cat</xf:label>
        <xf:value>cat</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Dog</xf:label>
        <xf:value>dog</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Bird</xf:label>
        <xf:value>bird</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Fish</xf:label>
        <xf:value>fish</xf:value>
    </xf:item>
</xf:select1>

Appearance

Full appearance (radio buttons)

Basic usage

<xf:select1 ref="selection" appearance="full">
    <xf:label>Radio Buttons</xf:label>
    <xf:hint>Standard radio buttons</xf:hint>:label>
    <xf:item>
        <xf:label>Cat</xf:label>
        <xf:value>cat</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Dog</xf:label>
        <xf:value>dog</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Bird</xf:label>
        <xf:value>bird</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Fish</xf:label>
        <xf:value>fish</xf:value>
    </xf:item>
</xf:select1>

Appearance

Multiple selection (select)

Compact appearance (list box)

Basic usage

<xf:select ref="selection" appearance="compact">
    <xf:label>Multipel List Box</xf:label>
    <xf:hint>Standard multiple-selection list</xf:hint>:label>
    <xf:item>
        <xf:label>Cat</xf:label>
        <xf:value>cat</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Dog</xf:label>
        <xf:value>dog</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Bird</xf:label>
        <xf:value>bird</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Fish</xf:label>
        <xf:value>fish</xf:value>
    </xf:item>
</xf:select>

Appearance

Full appearance (checkboxes)

Basic usage

<xf:select ref="selection" appearance="full">
    <xf:label>Checkboxes</xf:label>
    <xf:hint>Standard checkboxes</xf:hint>:label>
    <xf:item>
        <xf:label>Cat</xf:label>
        <xf:value>cat</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Dog</xf:label>
        <xf:value>dog</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Bird</xf:label>
        <xf:value>bird</xf:value>
    </xf:item>
    <xf:item>
        <xf:label>Fish</xf:label>
        <xf:value>fish</xf:value>
    </xf:item>
</xf:select>

Appearance

Using itemsets

In the examples above, the labels and values for the <select> and <select1> controls are declared in the control element with multiple <xf:item> elements.

Alternatively the label/value pairs can be pulled out from an instance. You do this with an <xf:itemset> element (instead of <xf:item> elements):

<xf:select1 ref="country" appearance="compact">
  <xf:itemset nodeset="instance('countries')/country">
    <xf:label ref="name"/>
    <xf:value ref="us-code"/>
  </xf:itemset>
</xf:select1>
[TODO: more on itemsets]

Extension attributes

  • xxf:refresh-itemsmore information here
  • xxf:encrypt-item-values: boolean attribute which locally overrides the oxf.xforms.encrypt-item-values property. If not present, the value of the property is used. If present, its value is used.

Use of the @class and @style attributes

Selection controls support the class and style attributes:
  • on xf:itemxf:choice, and xf:itemset
  • they are propagated to the resulting HTML markup when possible
  • they can be Attribute Value Templates (AVTs)
  • with xf:itemset, AVTs are evaluated relative to the current item
  • NOTE: the tree appearance only supports the class attribute
Example of using the class attribute with a hierarchical instance and itemset:

<xf:instance id="itemset">
    <items>
        <item id="1"/>
        <item id="2">
            <item id="2.1"/>
            <item id="2.2">
                <item id="2.2.1"/>
                <item id="2.2.2">
                    <item id="2.2.2.1"/>
                    <item id="2.2.2.2"/>
                </item>
            </item>
        </item>
    </items>
</xf:instance>

The following selection control with tree appearance uses the class attribute

<xf:select ref="value" appearance="xxf:tree">
    <xf:itemset ref="instance('itemset')//item" class="my-{if (exists(*)) then 'folder' else 'leaf'}">
        <xf:label ref="@id"/>
        <xf:value ref="@id"/>
    </xf:itemset>
</xf:select>

In this case, the class attribute is an AVT setting a different class depending on whether the item is a leaf item or not.

Internal appearance

When the xxf:internal appearance is used, the selection control does not have any visual representation on the client.

<xf:select id="my-select" ref="my-value" appearance="xxf:internal">
    <xf:itemset ref="instance('itemset')//item">
        <xf:label ref="@label"/>
        <xf:value ref="@value"/>
    </xf:itemset>
</xf:select>

This appearance is useful to implement custom selection controls with XBL and/or JavaScript.

Tree appearance

[REMOVED SINCE Orbeon Forms 4.8]

For select and select1

If you specify appearance="xxf:tree" on an <xf:select> or <xf:select1>, it will be rendered as a tree, as shown in the screenshots below. The nesting of the tree nodes in the UI will follow the nesting of the nodes you point to with <xf:itemset ref="...">.


<xf:select> tree


<xf:select1> tree


Styling of the nodes

You can use an AVT in the the class attribute on the <xf:itemset> to produce different CSS classes for different nodes, which you can then, for instance, be used to show different icons for different nodes. You'll find more information about this in how to add different icons to tree nodes.


Tooltip

If you with have a tooltip show when users mouse over the "+" and "-" icons, add the class xforms-show-tooltip on your <xf:select> or <xf:select1>. The tooltip will use the label of the node followed by either "Expand" or "Collapse". At this point, you can't change or localize this text.


Incremental

By default, <xf:select> and <xf:select1> with appearance="xxf:tree" behave as if incremental="true" was set: as soon as users select a node, the change is reflected in the instance. If you specify incremental="false" changes are only reflected when users move the focus to another control.

Controlling which tree nodes are initially open

[SINCE: 2010-11-15]

The <xf:itemset> element supports the xxf:open extension attribute, which determines which nodes of the tree are open when the tree is first rendered. You can use <xf:itemset xxf:open="true"> if you want all the nodes to be open. If you have a condition under which nodes should be open, use an AVT. For instance, the following will open just the first level of the tree. If you wanted to open all the nodes up to 3 levels of depth, you would instead write {count(ancestor-or-self::item) le 3}.

<xf:select ref="value">
    <xf:itemset ref="instance('itemset')//item"
            xxf:open="{count(ancestor-or-self::item) = 1}">
        <xf:label ref="label"/>
        <xf:value ref="value"/>
    </xf:itemset>
</xf:select>

A tree with only the first level open could look like:


If you don't use the xxf:open attribute, by default all the nodes leading to selected nodes are open, this so the selected values are all visible.

Menu appearance

[REMOVED SINCE Orbeon Forms 4.8]

Comments