Orbeon Search

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

XForms - Repeat

Contents

  1. 1 Basics
  2. 2 Repeat index
  3. 3 Deleting iterations with the <xforms:delete> action
  4. 4 Inserting iterations with the <xforms:insert> action
  5. 5  Using <xforms:trigger> to execute actions
  6. 6 Nested repeats
  7. 7 Iterating over plain values

Basics

A very common requirement of user interfaces consists in repeating visual elements, such as rows in a table or entries in a list. Those repeated sections usually (but not always) have an homogeneous aspect: they all have the same or a very similar structure. For example, multiple table rows will differ only in the particular content they display in their cells. An example of this is an invoice made of lines with each a description, unit price, and quantity.

XForms provides a very powerful mechanism to implement such repeated structures: the <xforms:repeat> element. You use <xforms:repeat> around XHTML elements or XForms controls. For example, to repeat a table row, you write:

<xforms:repeat>
    <xhtml:tr>
        ...
    </xhtml:tr>
</xforms:repeat>

This is not enough to be functional code: you need to indicate to the <xforms:repeat> element how many repetitions must be performed. This is done not by supplying a simple count value, but by binding the the element to a node-set with the nodeset attribute. Consider the following XForms instance:

<xforms:instance id="employees-instance">
    <employees>
        <employee>
            <first-name>Alice</first-name>
        </employee>
        <employee>
            <first-name>Bob</first-name>
        </employee>
        <employee>
            <first-name>Marie</first-name>
        </employee>
    </employees>
</xforms:instance>

Assuming you want to produce one table row per employee, add the following nodeset attribute:

<xforms:repeat nodeset="instance('employees-instance')/employee">
    <xhtml:tr>...</xhtml:tr>
</xforms:repeat>

This produces automatically three xhtml:tr rows. Note that we explicitly use the XForms instance() function, but you may not have to do so if that instance is already in scope. Then you display in each row the content of the first-name element for each employee:

<xforms:repeat nodeset="instance('employees-instance')/employee">
    <xhtml:tr>
        <xhtml:td>
            <xforms:output ref="first-name"/>
        </xhtml:td>
    </xhtml:tr>
</xforms:repeat>

This works because for each iteration, the context node for the ref attribute changes: during the first iteration, the context node is the first employee element of the XForms instance; during the second iteration, the second employee element, and so on.

Repeat index

Each <xforms:repeat> element has an associated index, representing the notion of a currently selected repeat iteration. This information can be used in CSS for example to highlight the currently selected iteration. The current index for a given repeat can be obtained with the XPath index() function.

NOTE: With XForms 1.1, each nested repeat keeps its own separate index value.

NOTE: XForms 1.1 does not explicitly limit in what type of XPath expressions index() can be used. However, in Orbeon Forms, it is strongly advised at the moment to only use index() within actions, and to avoid using it in control bindings and binds, as doing so may yield unpredictable results.

Deleting iterations with the <xforms:delete> action

<xforms:repeat> may be used purely for display purposes, but it can also be used for interactively editing repeated data. This includes allowing the user to delete and insert iterations. Two XForms actions are used for this purpose: <xforms:delete> and <xforms:insert>.

<xforms:delete> is provided with a nodeset attribute pointing to the collection of nodes to delete. It also has an optional at attribute, which contains an XPath expression returning the index of the element to delete. See how <xforms:delete> is used in these scenarios:

<!-- This deletes the last element of the collection -->
<xforms:delete nodeset="employees" at="last()"/>
<!-- This deletes the first element of the collection -->
<xforms:delete nodeset="employees" at="1"/>
<!-- This deletes the currently selected element of the collection (assuming the repeat id 'employee-repeat') -->
<xforms:delete nodeset="employees" at="index('employee-repeat')"/>
<!-- This deletes all elements of the collection -->
<xforms:delete nodeset="employees"/>

NOTE: Prior to XForms 1.1, the at attribute was mandatory. Since XForms 1.1, it is optional, and if omitted the nodeset attribute specifies all the nodes to remove.

Inserting iterations with the <xforms:insert> action

See also the Insert a new item into a repeat how-to guide.

<xforms:insert> has a nodeset attribute pointing to the collection into which the insertion must take place. If no origin attribute is specified, <xforms:insert> then considers the last element of that collection (and all its content if any) as a template for the new element to insert: it duplicates it and inserts it into the collection at a position you specify. In this case, the last element of a collection acts as a template for insertions:

<!-- This inserts a copy of the template before the last element of the collection -->
<xforms:insert nodeset="employees" at="last()" position="before"/>
<!-- This inserts a copy of the template after the last element of the collection -->
<xforms:insert nodeset="employees" at="last()" position="after"/>
<!-- This inserts a copy of the template before the first element of the collection -->
<xforms:insert nodeset="employees" at="1" position="before"/>
<!-- This inserts a copy of the template after the first element of the collection -->
<xforms:insert nodeset="employees" at="1" position="after"/>
<xforms:insert nodeset="employees" at="last()" position="after"/>
<!-- This inserts a copy of the template before the currently selected element of the collection -->
<xforms:insert nodeset="employees" at="index('employee-repeat')" position="before"/>
<!-- This inserts a copy of the template after the currently selected element of the collection -->
<xforms:insert nodeset="employees" at="index('employee-repeat')" position="after"/>
NOTE: Orbeon Forms supports the new XForms 1.1 features as well, including the origin and context attributes. The XForms 1.1 specification features a more complete list of example.

The at attribute contains an XPath expression returning the index of the element before or after which the insertion must be performed. The position element contains either after or before, and specifies whether the insertion is performed before or after the element specified by the at attribute.

 Using <xforms:trigger> to execute actions

Insertions and deletions are typically performed when the user of the application presses a button, with the effect of adding a new repeated element before or after the currently selected element, or of deleting the currently selected element. You use an xforms:trigger control and the XPath index() function for that purpose:

<xforms:trigger>
    <xforms:label>Add</xforms:label>
    <xforms:action ev:event="DOMActivate">
        <xforms:insert nodeset="employees" at="index('employee-repeat')" position="after"/>
    </xforms:action>
</xforms:trigger>

or:

<xforms:trigger>
    <xforms:label>Delete</xforms:label>
    <xforms:action ev:event="DOMActivate">
        <xforms:delete nodeset="employees" at="index('employee-repeat')"/>
    </xforms:action>
</xforms:trigger>

Note that we use xforms:action as a container for <xforms:insert> and <xforms:delete>. Since there is only one action to execute, xforms:action is not necessary, but it may increase the legibility of the code. It is also possible to write:

<xforms:trigger>
    <xforms:label>Add</xforms:label>
    <xforms:insert ev:event="DOMActivate" nodeset="employees" at="index('employee-repeat')" position="after"/>
</xforms:trigger>

or:

<xforms:trigger>
    <xforms:label>Delete</xforms:label>
    <xforms:delete ev:event="DOMActivate" nodeset="employees" at="index('employee-repeat')"/>
</xforms:trigger>

Notice in that case how ev:event="DOMActivate" has been moved from the enclosing xforms:action to the <xforms:insert> and <xforms:delete> elements.

Nested repeats

It is often desirable to nest repeat sections. Consider the following XForms instance representing a company containing departments, each containing a number of employees:

<xforms:instance id="departments">
    <departments>
        <department>
            <name>Research and Development</name>
            <employees>
                <employee>
                    <first-name>John</first-name>
                </employee>
                <employee>
                    <first-name>Mary</first-name>
                </employee>
            </employees>
        </department>
        <department>
            <name>Support</name>
            <employees>
                <employee>
                    <first-name>Anne</first-name>
                </employee>
                <employee>
                    <first-name>Mark</first-name>
                </employee>
                <employee>
                    <first-name>Sophie</first-name>
                </employee>
            </employees>
        </department>
    </departments>
</xforms:instance>

This document clearly contains two nested sections subject to repetition:

  • Departments: a node-set containing all the department elements can be referred to with the following XPath expression: instance('departments')/department.

  • Employees: a node-set containing all the employee elements can be referred to with the following XPath expression: instance('departments')/department/employees/employee. However, if the context node of the XPath expression points to a particular department element, then the following relative XPath expression refers to all the employee elements under that department element: employees/employee.

Following the example above, here is how departments and employees can be represented in nested tables with XForms:

<xhtml:table>
    <xforms:repeat nodeset="instance('departments')/department">
        <xhtml:tr>
            <xhtml:td>
                <xforms:output ref="name"/>
            </xhtml:td>
            <xhtml:td>
                <xhtml:table>
                    <xforms:repeat nodeset="employees/employee">
                        <xhtml:tr>
                            <xhtml:td>
                                <xforms:output ref="first-name"/>
                            </xhtml:td>
                        </xhtml:tr>
                    </xforms:repeat>
                </xhtml:table>
            </xhtml:td>
        </xhtml:tr>
    </xforms:repeat>
</xhtml:table>

In the code above, the second <xforms:repeat>'s nodeset expression is interpreted relatively to the department element of the parent <xforms:repeat> for each iteration of the parent's repetition. During the first iteration of the parent, the "Research and Development" department is in scope, and employees/employee refers to the two employees of that department, John and Mary. During the second iteration of the parent, the "Support" department is in scope, and employees/employee refers to the three employees of that department, Anne, Mark and Sophie.

Iterating over plain values

XForms 1.1 only specifies iterating over instance data nodes (elements or attributes). As of January 2010, Orbeon Forms supports iterating over values, for example:

<xforms:repeat nodeset="(1 to 10)">
    <xforms:output value="position()"/>
    <xforms:output value="."/>
</xforms:repeat>

In this case, the context item within the repeat is a number, not a node.

NOTE: It is hoped that the XForms specification will include this possibility in the future. Possibly, a new attribute, such as sequence, could be proposed, since a sequence of numbers is technically not a node-set!