What is an XForms repeat?

The repeat element allows you to map your XForms user interface (UI) elements to a homogeneous collection in your XForms document's XML data instance. A "homogenous collection" is taken to be a series of nodes of the same datatype at the same level in the document. For example, in Listing 1, below, the set of bread elements is a homogeneous collection of nodes within the XML instance.

        
<xforms:instance id="in-stock">
    <in-stock>
        <groceries>
            <perishable>          
                <bread brand="Wonder" quantity="1"/>
              <bread brand="Merita" quantity="2"/>
              <bread brand="Arnold" quantity="4"/>             
            </perishable>
        </groceries>
    </in-stock>
</xforms:instance>

To associate a repeat element with the homogeneous set, you simply refer to it by specifying XPath in the nodeset attribute of a repeat element, as in Listing 2, below.

        
<xforms:repeat id="bread-repeat" nodeset="instance('in-stock')/perishable/bread">
    ...

Notice also in Listing 2 that the repeat was given an id value, so we can refer to it later from other XForms constructs.

Now, you can place UI elements within the repeat element, and when you view the form the UI elements will be "unrolled", so that one control will appear for each member in the homogeneous set. Listing 3 shows an XForms input UI element bound to an attribute within the homogeneous set from Listing 1. Notice that the reference into the data instance from the input element is made relative to the nodeset defined for the surrounding repeat.

        
<xforms:repeat id="bread-repeat" 
               nodeset="instance('in-stock')/groceries/perishable/bread">
    <xforms:input ref="@brand">
        <xforms:label>Brand of bread: </xforms:label>
    </xforms:input>      
</xforms:repeat>

Listing 4 gives an indication of the "unrolled" version that really would be rendered. (You would never see this source when developing the form; it's just here to demonstrate a renderer's interpretation of the repeat construct.)

        
    <xforms:input ref="instance('in-stock')/groceries/perishable/bread[1]/@brand">
        <xforms:label>Brand of bread: </xforms:label>
    </xforms:input>
    <xforms:input ref="instance('in-stock')/groceries/perishable/bread[2]/@brand">
        <xforms:label>Brand of bread: </xforms:label>
    </xforms:input>
    <xforms:input ref="instance('in-stock')/groceries/perishable/bread[3]/@brand">
        <xforms:label>Brand of bread: </xforms:label>
    </xforms:input>

Figure 1 shows what this construct looks like when rendered in Mozilla Firefox with the XForms Extension (see Resources for information on how to get the Firefox XForms Extension).

Formatting repeats as tables

Very often, it makes sense to display data from a homogeneous set in a table format. In the XForms Extension for Firefox, formatting repeats into a display having the appearance of a table requires some work with cascading stylesheets (CSS).

First, the source in Listing 5 shows the markup in the body of the document, to which the CSS definitions will apply. Note that the table and column headers are declared with XHTML markup. However, the "body" of the table consists entirely of an XForms repeat.

<xhtml:table>
    <xhtml:tr>
        <xhtml:thead>
            <xhtml:th>Brand Name</xhtml:th>
            <xhtml:th>Quantity</xhtml:th>
        </xhtml:thead>
    </xhtml:tr>
    <xforms:repeat id="bread-repeat" 
                   nodeset="instance('in-stock')/groceries/perishable/bread">
        <xforms:output ref="@brand">
            <xforms:label/>
        </xforms:output>
        <xforms:input ref="@quantity">
            <xforms:label/>
        </xforms:input>
    </xforms:repeat>
</xhtml:table>

Listing 6 gives the style definition we'll use for our repeat. The CSS declarations are placed within an XHTML style tag (you can also refer to CSS stored in an external file using the src attribute on the style tag).

        
<xhtml:style type="text/css">
    @namespace xforms url("http://www.w3.org/2002/xforms");
    @namespace xhtml url("http://www.w3.org/1999/xhtml");

    xhtml|th 
    { 
        width: 240px; 
    }

    xforms|repeat .xf-repeat-item 
    {
        display: table-row;
        width:   480px;
    }

    xforms|repeat xforms|output, xforms|repeat xforms|input
    {
       display:          table-cell;
       border:           thin;
       border-style:     solid;
       width:            240px;
       text-align:       center;
       background-color: lightgray;  
    }
</xhtml:style>

Listing 6 approaches the styling by declaring that each item (that is, each row) in the repeat is to be displayed as a row in a table. Then, the next declaration asserts that each XForms output and input control within a repeat will be treated as a table cell, having a solid border and a light gray background.

Figure 2 shows the result when rendered in Mozilla Firefox with the XForms Extension.

There are other stylings that could be used to get a similar effect in Firefox. Furthermore, other XForms renderers might permit different approaches altogether. One example of an alternate approach is the use of some optional attributes defined in the XForms 1.0 specification, particularly repeat-nodeset. These attributes could be placed on a non-XForms element to define a repeating structure that applies to that element's children. Listing 7 shows an example of the usage of repeat-nodeset on the XHTML table element.

    
<xhtml:table>
    <xhtml:tr>
        <xhtml:thead>
            <xhtml:th>Brand Name</xhtml:th>
            <xhtml:th>Quantity</xhtml:th>
        </xhtml:thead>
    </xhtml:tr>
</xhtml:table>
<xhtml:table xforms:repeat-nodeset="instance('in-stock')/groceries/perishable/bread">
    <xhtml:tr>
        <xhtml:td>
            <xforms:output ref="@brand">
                <xforms:label/>
            </xforms:output>
        </xhtml:td>
        <xhtml:td>
            <xforms:input ref="@quantity">
                <xforms:label/>
            </xforms:input>          
        </xhtml:td>      
    </xhtml:tr>
</xhtml:table>

Using the repeat attributes on non-XForms elements is an elegant approach. It's supported by some XForms implementations, including the XForms Extension for Firefox.

Inserting and deleting rows

So far, we've looked at presenting repeating structures as they exist in the XML data instance. However, XForms allows users to do much, much more with that data. In particular, it's very common to want to add a new row to a table, or delete an existing row. Listing 8 shows the markup for permitting the user to trigger deletion and insertion of rows in your repeating set.

<xforms:trigger>
    <xforms:label>Insert Row</xforms:label>
    <xforms:insert ev:event="DOMActivate"
                   at="index('bread-repeat')" position="after"
                   nodeset="instance('in-stock')/groceries/perishable/bread"/>
</xforms:trigger>
<xforms:trigger>
    <xforms:label>Delete Row</xforms:label>
    <xforms:delete ev:event="DOMActivate"
                   at="index('bread-repeat')"
                   nodeset="instance('in-stock')/groceries/perishable/bread"/>
</xforms:trigger>

Listing 8 introduces the concept of a repeat "index". Notice the use of the index() function within the at attribute of the insert and delete actions. The value given in the value of the at attribute represents the 1-based index into the repeat's data set at which the insert or delete will occur. By using the index() function within the value of this attribute, we are specifying that the insert or delete will occur at the currently selected row in the repeat. In the case of the delete action, this means that the currently selected row will be deleted. For the insert action, this means that the new row will be inserted either directly before or after the row at the selected index. Whether the new row is inserted before or after the currently selected row depends on the value given in the insert element's position attribute.

When an insert action is triggered, the last row of the repeat is cloned, and it is that clone of the repeat that is inserted. This generally means that the values for the elements and attributes of that row are brought along as well. As this may not be the desired behavior, you may want to follow an insert with a setvalue action to reset the value, as in Listing 9. The index() function is again used to specify the currently-selected row of the repeat as the one on which the setvalue action will occur. This suits the intended purpose -- to target the just-inserted row -- since the insert action resets the repeat's index to be that of the just-inserted row.

<xforms:trigger>
    <xforms:label>Insert Row</xforms:label>
    <xforms:action ev:event="DOMActivate">
        <xforms:insert at="index('bread-repeat')"
                       position="after" 
                       nodeset="instance('in-stock')/groceries/perishable/bread"/>
        <xforms:setvalue 
                    ref="instance('in-stock')/
                         groceries/perishable/bread[index('bread-repeat')]/@quantity"
                    value="0"/>
    </xforms:action>
</xforms:trigger>

Implementing triggers for inserting and deleting rows in a repeat is a very common pattern. In fact, automated XForms-generation tools, specifically the IBM® XML Forms Generator (see Resources) will automatically generate triggers for addition and deletion with every repeat.

Preventing deletion of the last row

In the previous section, we established that an insert action clones the last row in the repeat. This is very bad news when the repeat no longer has any rows, possibly because the user has triggered delete actions on all of them. The net result is that, in the earlier examples, if all rows are deleted, the insert action will no longer do anything.

Therefore, you may wish to prevent deletion of the last row. Listing 10 shows one approach, which is to bind the "Delete" trigger to a node in the data model, and then to make that node non-relevant when the count of nodes in the set reaches 1.

<xforms:instance id="trigger-controller">
    <trigger-sets>
        <trigger-set>
            <insert-trigger/>
            <delete-trigger/>
        </trigger-set>
    </trigger-sets>
</xforms:instance>
<xforms:bind nodeset="instance('trigger-controller')/trigger-set/delete-trigger"
             relevant="count(instance('in-stock')/groceries/perishable/bread) > 1"/>
		                 
        ...
        
<xforms:trigger ref="instance('trigger-controller')/trigger-set/insert-trigger">
    <xforms:label>Insert Row</xforms:label>
    <xforms:insert ev:event="DOMActivate" at="index('bread-repeat')"
                   position="after" 
                   nodeset="instance('in-stock')/groceries/perishable/bread"/>
</xforms:trigger>
<xforms:trigger ref="instance('trigger-controller')/trigger-set/delete-trigger">
    <xforms:label>Delete Row</xforms:label>
    <xforms:delete ev:event="DOMActivate" at="index('bread-repeat')"
                   nodeset="instance('in-stock')/groceries/perishable/bread"/>
</xforms:trigger>

When the node referenced by the trigger becomes non-relevant, the trigger becomes "unavailable". In Firefox, the default behavior is for the button to disappear from the page, as shown in Figure 3, which shows the form before and after the next-to-last row is deleted.

You may wish to experiment with other approaches using the "relevant" property; for example, always making the last row of the repeat non-relevant. That way, the last row can never be selected, and therefore can never be deleted when you are depending on the repeat index to determine the delete location.

Listing 11 shows how you might add a "prototype" entry to your data instance, and then add binds to make that last entry always non-relevant. To ensure that the last row is never displayed, a new CSS entry is made, keying on the ".disabled" CSS cue. The repeat element and its contents require no change at all for this approach.

<xforms:model>
    <xforms:instance id="in-stock">
        <in-stock>
            <groceries>
                <perishable>
                    <bread brand="Wonder" quantity="1" />
                    <bread brand="Merita" quantity="2" />
                    <bread brand="Arnold" quantity="4" />
                    <bread brand="Not sure yet" quantity="0" />
                </perishable>
            </groceries>
        </in-stock>
    </xforms:instance>
    <xforms:bind nodeset="instance('in-stock')/groceries/perishable/bread
                          [count(instance('in-stock')/groceries/perishable/bread)]/
                          @brand"
		 relevant="false()"/>
    <xforms:bind nodeset="instance('in-stock')/groceries/perishable/bread
                          [count(instance('in-stock')/groceries/perishable/bread)]/
                          @quantity"
		 relevant="false()"/>
</xforms:model>
<xhtml:style type="text/css">
    @namespace xforms url("http://www.w3.org/2002/xforms");
    xforms|*:disabled { display: none; }
</xhtml:style>

For now, using a technique like this is necessary to prevent deletion of your insert prototype. However, there is help on the horizon. The XForms 1.1 specification will address this and other shortcomings with the insert and delete actions, making workarounds like the ones shown here no longer necessary.

Nesting repeats

The power of XForms really shows itself when you have data that contains homogeneous data sets at different levels, with one nested within the other. For example, Listing 12 shows a data instance in which a top-level homogeneous set of elements consists of the three item elements. Then, each item element contains a set of its own info elements.

<xforms:instance id="in-stock">
    <in-stock>
        <groceries>
            <perishable>
                <item type="bread">
                    <info brand="Wonder" quantity="1"/>
                    <info brand="Merita" quantity="2"/>
                    <info brand="Arnold" quantity="4"/>	                    
                </item>
                <item type="peanut butter"">
                    <info brand="Skippy" quantity="2"/>		                
                    <info brand="Jif" quantity="1"/>
                </item>
                <item type="jelly">
                    <info brand="Smuckers" quantity="1"/>
                    <info brand="Welch's" quantity="3"/>	                    
                </item>
            </perishable>
        </groceries>
    </in-stock>
</xforms:instance>

XForms makes it easy to iterate over nested sets like this through the nesting of the corresponding repeats. Listing 13 shows how to do it.

<xforms:repeat id="bread-repeat" nodeset="instance('in-stock')/groceries/perishable/item">
    <xforms:output ref="@type">
        <xforms:label>Item type: </xforms:label>
    </xforms:output>
    <xforms:repeat id="bread-repeat" nodeset="info">
        <xforms:output ref="@brand">
            <xforms:label>Brand: </xforms:label>
        </xforms:output>
        <xforms:input ref="@quantity">
            <xforms:label>Quantity: </xforms:label>
        </xforms:input>
    </xforms:repeat>
    <xhtml:hr/>
</xforms:repeat>

Listing 13 defines an output within the outermost repeat, for which each item type is displayed. Then, an inner repeat iterates over the info elements within each item. Notice that the XPath in the inner repat's nodeset attribute is defined relative to the nodeset of its containing repeat. Figure 4 shows how these nested repeats would look in Firefox.

The power of XForms shows itself once again with the fact that there are no limits to the depth with which you can nest repeats. The only constraints are renderer performance and the desire to maintain a clean, easy-to-navigate interface for the end-user.

Managing a repeat's index

During our discussion of the insert and delete actions, we touched on the concept of the repeat's index -- that is, the one-based index of the currently selected "row".

The user may make the selection, or you can force a selection programmatically in one of two ways.

Firstly, you can specify the index of the repeat at the time the form is first rendered by specifying an integer value for the attribute of repeat called startindex. Unlike some of the other XForms facilities for dealing with indices, you cannot specify an XPath expression here; according to the XForms 1.0 specification, only a positive integer value will do.

Secondly, you may also set the index of a repeat with the setindex action in response to the user activating a trigger, or perhaps as part of some other action (for example, resetting the index to a desired value after an insert or delete). Listing 14 gives some markup which initially sets the index to 2, and then allows the user to enter a value for the index and set it to that value by activating the trigger labeled "Select".

    <xforms:instance id="target-index">
        <target-index>
            <value>1</value>
        </target-index>
    </xforms:instance>
		    
    ...
		    
    <xhtml:table>
        <xhtml:tr>
            <xhtml:thead>
                <xhtml:th>Brand Name</xhtml:th>
                <xhtml:th>Quantity</xhtml:th>
            </xhtml:thead>
        </xhtml:tr>
        <xforms:repeat id="bread-repeat" 
                       nodeset="instance('in-stock')/groceries/perishable/bread" 
                       startindex="2">		      
            <xforms:output ref="@brand">
                <xforms:label/>
            </xforms:output>
            <xforms:input ref="@quantity">
                <xforms:label/>
            </xforms:input>
        </xforms:repeat>
    </xhtml:table>
	    
    <xforms:input ref="instance('target-index')/value">
        <xforms:label>Target Index: </xforms:label>
    </xforms:input>
    <xforms:trigger>
        <xforms:label>Select</xforms:label>
        <xforms:setindex ev:event="DOMActivate"
                        repeat="bread-repeat" 
                        index="instance('target-index')/value"/>
    </xforms:trigger>		    

In Listing 14, a data instance has been added to hold the desired value of the repeat index. The input control is bound to this data, so whenever a user enters a new value, that value gets placed in the value element. Finally, the setvalue action tied to the trigger references that same value element in its index attribute, which can take an XPath expression. Figure 5 shows the resulting form in Firefox.

Figure 5 shows the selected row having a different appearance from the other rows. Without a visual cue like this, it's likely to be unclear to the user which row is currently selected. You can use CSS to provide the user with an indicator of the currently selected row. In Firefox, CSS such as that shown in Listing 15 targets the selected index.

xforms|repeat .xf-repeat-index > xforms|*
{
    color:            white;
    background-color: black;
    border:           none;
}

The number attribute

The number attribute on the XForms repeat element is a hint to the renderer as to the number of repeat items (or rows) to display at any one time. Support for this attribute is optional for XForms processors, so many renderers do not support it. However, some renderers, such as the FormsPlayer plug-in for Microsoft® Internet Explorer (see Resources), do support the number attribute.

Use of the number attribute can permit a cleaner presentation, particularly of repeats over very large sets of data. It may also improve performance, as not every item in the repeat will need to have its associated controls redrawn when the data changes.

Let's say that, using the data instance from Listing 1, we want only one row of data to be presented at a time. We would simply add a value of 1 to the repeat element as defined in Listing 2. The result would be as shown in Listing 16.

<xforms:repeat id="bread-repeat" 
               nodeset="instance('in-stock')/groceries/perishable/bread" 
               number="1">
...

Now, it's great that so much space is saved by showing only one repeat row at a time, but a user of this form may want to manipulate the data for a row other than the one initially shown. You can give users the opportunity to access other repeat items by allowing the user to set the current index of the repeat. Listing 17 shows how to enable this by leveraging the setindex action.

<xforms:trigger>
    <xforms:label>< < Previous</xforms:label>
    <xforms:setindex ev:event="DOMActivate" repeat="bread-repeat"
                     index="index('bread-repeat') - 1"/>
</xforms:trigger>
<xforms:trigger>
    <xforms:label>Next > ></xforms:label>
    <xforms:setindex ev:event="DOMActivate" repeat="bread-repeat"
                     index="index('bread-repeat') + 1"/>
</xforms:trigger>

Listing 17 provides buttons labeled "< < Previous" and "Next > >", which when pressed will decrement and increment, respectively, the index of the repeat. This allows the form's user to scroll back and forth through the data in the repeat.

Figure 6 shows what our scrollable repeat would look like in Internet Explorer, using the FormsPlayer plug-in.

The power of XForms

XForms repeats are one of the more powerful constructs in XForms. If you have not done so already, go ahead and grab a renderer -- such as the free download of the XForms Extension for Mozilla Firefox (see Resources) -- and try these techniques out for yourself.

Resources

Learn

• Dig into XForms at the home page of W3C XForms, which has links to the official XForms specification, as well as to a wide variety of XForms rendering options.
  
  
• Find out more about XHTML, Cascading Style Sheets (CSS), XML, XML Events, XPath, and other related standards at the W3C site.
  
  

Get products and technologies

• Mozilla XForms: Render your standards-compliant forms in Mozilla Firefox using this plug-in.
  
  
• Get MozzIE, an open-source control that allows you to render XForms in Internet Explorer.
  
  
• Try FormsPlayer, a plug-in for Internet Explorer that renders XForms.
  
  
• XML Forms Generator: Create functional, standards-compliant forms with a click of the mouse using this Eclipse-based tool from alphaWorks.
  
  
• Visual XForms Designer: Check out the home page, with links to installation instructions, prerequisites, and the forum.
  
  
• Compound XML Document Toolkit: Explore other open-standard XML markups, including Scalable Vector Graphics (SVG), MathML, VoiceXML, and Synchronized Multimedia Integration Language (SMIL).
  
  

Discuss

• Get answers to your questions about the Visual XForms Designer on its discussion forum.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• What is an XForms repeat?
• Formatting repeats as tables
• Inserting and deleting rows
• Preventing deletion of the last row
• Nesting repeats
• Managing a repeat's index
• The number attribute
• The power of XForms
• Resources
• About the authors
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, pureXML and evolving your XML schemas you can easily increase development and application performance.

---

• Try: Download a free trial version of DB2 Express-C, which includes pureXML technology that is ideally suited for managing XML schema and relational data.
• Article: See how to use DB2's pureXML schema evolution capabilities, that evolve schemas without making any changes to your applications.
• Tutorial: This tutorial shows you how using a native DB2 XML database enables changes in an existing XML schema to also appear in your application code.
• Demo: This demo shows you how easy it is to create a DB2 database for storing XML data.
• Buy: DB2 9 for Linux, UNIX and Windows

Dig deeper into XML on developerWorks

Discover knowledge paths

Skill-building guides for XML, Linux, open source, cloud, Java, business analytics, and more.

Special offers