The presentation of this document has been augmented to identify changes from a previous version. Three kinds of changes are highlighted: new, added text, changed text, and deleted text.

9 XForms User Interface

9.4 The XForms Tree Module

Element Attributes Minimal Content Model
tree Common, UI Common, Single Node Binding (optional), filter? label?,treeitem (help, hint, alert, etc?)
tree-item Common, UI Common label? (help, hint, alert, etc?)

9.4.1 The tree Element

Common Attributes: Common, UI Common, Single Node Binding

Special Attributes:

filter

Optional XPath expression used to filter the nodes that are shown by the tree element. The tree element will only contain the relevant element nodes that are both in the bound node tree and the filter node-set.

The filter node-set is computed by evaluating the XPath expression. The context of this expression is the bound node.

The tree element allows the user to navigate a indefinitely deep nested structure. The structure shown to the user is rooted at the bound node and includes all relevant element nodes including the bound node, that are not filtered out. The tree element has a mandatory unique id. The tree element has a mandatory treeitem child element.

The tree control is only used to select a context node, which is exposed to the rest of the user interface using the nodeindex() XPath function. The tree control itself does not allow editing the structure or the individual nodes. Note that nodes, which are irrelevant, and their descendants are not presented to the user.

Informative: In a graphical implementation, the tree can be represented as a tree widget, which can be opened or collapsed by the user [add screenshot here].

Editorial note: Add screenshot of tree control 
Editorial commentary, not intended for final publication.

9.4.2 The treeitem Element

Common Attributes: Common, UI Common

The treeitem element's label (executed with the context of corresponding node, with it as the only node in the context nodeset) is used to determine the label of each node.

7 XPath Expressions in XForms

7.11 Node-set Functions

7.11.2 The nodeindex() Function

node-set nodeindex(string)

This function takes an idref of an tree widget, as an argument and returns the instance node, which corresponds to the currently selected node in a tree widget.

The argument is converted to a string as if by a call to the string function. This string is treated as an IDREF, which is matched against tree elements in the containing document. If a match is located, this function returns a node-set containing just the instance node, which corresponds to the currently selected node in a tree widget. In all other cases, an empty node-set is returned.

Example:

Folder and file selector using a tree control
<instance xmlns="xformsns...">
    <data xmlns="">
       <folder name="xxx">
           <folder name="xxx">
               <folder name="xxx">
                   <file name="xxx" description="xxx" xxx="xxx"/>
               </folder>
               <file name="xxx" description="xxx" xxx="xxx"/>
               <file name="xxx" description="xxx" xxx="xxx"/>
           </folder>
       </folder>
    </data name="xxx">
</instance>

<group xmlns="xformsns...">
  <tree ref="/data/folder" id="folders">
    <label>The directory structure</label>
    <treeitem>
        <label ref="@name"/>
    </treeitem>
  </tree>

  <group ref="nodeindex('folders')">
    <group ref="self::node()[localname()='folder']>
       <label>Folder</label>
       <input ref="@name"/>
    </group>
    <group ref="self::node()[localname()='file']>
       <label>File</label>
       <input ref="@name"/>
       <input ref="@description"/>
    </group>
  </group>
</group>

The above example would display a tree of folders and files. When a user selects a node, an editor for that node is shown in the group below.

Example:

Folder selector using a tree control with a node filter.
<instance xmlns="xformsns...">
  <data xmlns="">
    <folder name="xxx">
      <folder name="xxx">
        <folder name="xxx">
          <file name="xxx" description="xxx" xxx="xxx"/>
        </folder>
        <file name="xxx" description="xxx" xxx="xxx"/>
        <file name="xxx" description="xxx" xxx="xxx"/>
      </folder>
    </folder>
  </data name="xxx">
</instance>

<group xmlns="xformsns...">
  <tree ref="/data/folder" filter="//folder" id="folders">
    <label>The directory structure</label>
    <treeitem>
      <label ref="@name"/>
    </treeitem>
  </tree>

  <group ref="nodeindex('folders')">
    <group ref="self::node()>
      <label>Folder</label>
      <input ref="@name"/>
    </group>
  </group>
</group>

The above example would display a tree of folders. When a user selects a node, an editor for that node is shown in the group below.

A node filter is used to filter out the file nodes.