Selection Controls

Site map

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

Sites, projects, and companies using Orbeon Forms
edited by Alessandro Vernet
attachment from Alessandro Vernet
Form Runner Home Page
edited by Alessandro Vernet
Orbeon Forms Test Plan
edited by Erik Bruchez
Version 3.0
edited by Erik Bruchez
Process Button
removed by Erik Bruchez
View All

Documentation‎ > ‎II. Developer and Administrator Guide‎ > ‎XForms - Controls‎ > ‎

Selection Controls

Single selection (select1)

Minimal appearance (dropdown)

Basic usage

<xforms:select ref="selection" appearance="compact">

   <xforms:label>Dropdown</xforms:label>

   <xforms:hint>Standard dropdown</xforms:hint>:label>

   <xforms:item>

   <xforms:label>Cat</xforms:label>

   <xforms:value>cat</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Dog</xforms:label>

   <xforms:value>dog</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Bird</xforms:label>

   <xforms:value>bird</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Fish</xforms:label>

   <xforms:value>fish</xforms:value>

   </xforms:item>

</xforms:select>

Appearance

Compact appearance (list box)

Basic usage

<xforms:select1 ref="selection" appearance="compact">

   <xforms:label>Single List Box</xforms:label>

   <xforms:hint>Standard single-selection list</xforms:hint>:label>

   <xforms:item>

   <xforms:label>Cat</xforms:label>

   <xforms:value>cat</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Dog</xforms:label>

   <xforms:value>dog</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Bird</xforms:label>

   <xforms:value>bird</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Fish</xforms:label>

   <xforms:value>fish</xforms:value>

   </xforms:item>

</xforms:select1>

Appearance

Full appearance (radio buttons)

Basic usage

<xforms:select1 ref="selection" appearance="full">

   <xforms:label>Radio Buttons</xforms:label>

   <xforms:hint>Standard radio buttons</xforms:hint>:label>

   <xforms:item>

   <xforms:label>Cat</xforms:label>

   <xforms:value>cat</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Dog</xforms:label>

   <xforms:value>dog</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Bird</xforms:label>

   <xforms:value>bird</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Fish</xforms:label>

   <xforms:value>fish</xforms:value>

   </xforms:item>

</xforms:select1>

Appearance

Multiple selection (select)

Compact appearance (list box)

Basic usage

<xforms:select ref="selection" appearance="compact">

   <xforms:label>Multipel List Box</xforms:label>

   <xforms:hint>Standard multiple-selection list</xforms:hint>:label>

   <xforms:item>

   <xforms:label>Cat</xforms:label>

   <xforms:value>cat</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Dog</xforms:label>

   <xforms:value>dog</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Bird</xforms:label>

   <xforms:value>bird</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Fish</xforms:label>

   <xforms:value>fish</xforms:value>

   </xforms:item>

</xforms:select>

Appearance

Full appearance (checkboxes)

Basic usage

<xforms:select ref="selection" appearance="full">

   <xforms:label>Checkboxes</xforms:label>

   <xforms:hint>Standard checkboxes</xforms:hint>:label>

   <xforms:item>

   <xforms:label>Cat</xforms:label>

   <xforms:value>cat</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Dog</xforms:label>

   <xforms:value>dog</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Bird</xforms:label>

   <xforms:value>bird</xforms:value>

   </xforms:item>

   <xforms:item>

   <xforms:label>Fish</xforms:label>

   <xforms:value>fish</xforms:value>

   </xforms:item>

</xforms: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 <xforms:item> elements.

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

<xforms:select1 ref="country" appearance="compact"> <xforms:itemset nodeset="instance('countries')/country"> <xforms:label ref="name"/> <xforms:value ref="us-code"/> </xforms:itemset> </xforms:select1>

[TODO: more on itemsets]

Extension attributes

xxforms:refresh-items: more information here
xxforms: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 xforms:item, xforms:choice, and xforms:itemset
they are propagated to the resulting HTML markup when possible
they can be Attribute Value Templates (AVTs)
with xforms: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:

<xforms: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>
</xforms:instance>

The following selection control with tree appearance uses the class attribute

<xforms:select ref="value" appearance="xxforms:tree">
    <xforms:itemset ref="instance('itemset')//item" class="my-{if (exists(*)) then 'folder' else 'leaf'}">
        <xforms:label ref="@id"/>
        <xforms:value ref="@id"/>
    </xforms:itemset>
</xforms: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 xxforms:internal appearance is used, the selection control does not have any visual representation on the client.

<xforms:select id="my-select" ref="my-value" appearance="xxforms:internal">

   <xforms:itemset ref="instance('itemset')//item">

   <xforms:label ref="@label"/>

   <xforms:value ref="@value"/>

   </xforms:itemset>

</xforms:select>

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

Tree appearance

For select and select1

If you specify appearance="xxforms:tree" on an <xforms:select> or <xforms: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 <xforms:itemset ref="...">.

<xforms:select> tree

<xforms:select1> tree

Styling of the nodes

You can use an AVT in the the class attribute on the <xforms: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 <xforms:select> or

<xforms: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, <xforms:select> and <xforms:select1> with appearance="xxforms: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 <xforms:itemset> element supports the xxforms:open extension attribute, which determines which nodes of the tree are open when the tree is first rendered. You can use <xforms:itemset xxforms: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}.

<xforms:select ref="value">

   <xforms:itemset ref="instance('itemset')//item"             xxforms:open="{count(ancestor-or-self::item) = 1}">

   <xforms:label ref="label"/>

   <xforms:value ref="value"/>

   </xforms:itemset>

</xforms:select>

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

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

Menu appearance

[TODO]

Comments