table

Each time a new row is added to the table, the template items are duplicated to create the new row. This occurs when the elements in the data model that are linked to those items are duplicated. This allows the table to expand to any size while ensuring that data for each row in the table is still maintained in the data model.

The template row is created within an xforms:repeat option. This option is used to group the items that create the template row, and also links the row to particular portion of the data model. The template items can be configured with any location relative to one another. This means that they need not appear in horizontal succession.

Rows are added or removed from a table using the xforms:insert and xforms:delete action respectively. For more information about actions, see XForms actions.

Available Options

active, bgcolor, border, borderinfo, first, focused, itemlocation, itemnext, itemprevious, last, next, previous, printbgcolor, printvisible, rowpadding, visible, xformsenabled, xformsreadonly, xformsrequired, xformsvalid, xforms:repeat

Example

Before creating a table, you should create the data model that the table will reflect. The data model should group the elements you want in the table by rows. For example, suppose you wanted to create a purchase order form. Your table might collect three pieces of information: what the user wants to purchase, how many units they want to purchase, and what the cost of that item is. You might create the following data model to store that information:

   <po>
      <order>
         <row>
            <product></product>
            <quantity></quantity>
            <lineTotal></lineTotal>
         </row>
      </order>
   </po>

As you can see, the three data elements are contained by a <row> element. This will allow us to duplicate any number of rows.

For the actual table, we will use the following items to reflect the data model: a popup that lets the user select which product to purchase, a field that lets them enter a quantity for the product, and a label that displays the cost of the products. Furthermore, these items will be contained within an xforms:repeat option, we will link that option to the <row> element in the data model, as shown:

   <table sid="itemsTable">
      <xforms:repeat nodeset="order/row">
         <popup sid="Product">
            <xforms:select1 appearance="minimal" ref="product">
               <xforms:label>Choose product</xforms:label>
               <xforms:item> 
                  <xforms:label>Widget</xforms:label>
                  <xforms:value>widget</xforms:value>
               </xforms:item>
               <xforms:item>
                  <xforms:label>Gadget</xforms:label>
                  <xforms:value>gadget</xforms:value>
               </xforms:item>
            </xforms:select1>
         </popup>
         <field sid="Qty">
            <xforms:input ref="quantity">
               <xforms:label></xforms:label>
            </xforms:input>
         </field>
         <label sid="LineTotal">
            <xforms:output ref="lineTotal"></xforms:output>
            <value></value>
         </label>
      </xforms:repeat>
   </table>

When the user adds rows to the table, the description of the table does not change. Instead, the data model expands to include the new data. For instance, if the user had entered two rows of data, your data model might look like this:

   <po>
      <order>
         <row>
            <product>widget</product>
            <quantity>2</quantity>
            <lineTotal>2.00</lineTotal>
         </row>
         <row>
            <product>gadget</product>
            <quantity>5</quantity>
            <lineTotal>15.00</lineTotal>
         </row>
      </order>
   </po>

Based on this data model, the Viewer will create two rows of the popup, field, and label items, with no changes to the markup for the table item. This occurs because the nodeset in the xforms:repeat binds to every <row> element in the <order>, duplicating the template items for each.

Usage details

1. To add rows to a table or remove rows from a table, you must use the xforms:insert and xforms:delete actions respectively. For more information about these actions, refer to XForms actions.
2. The context() function can be used in the value attribute of the xforms:setvalue action to copy a value from within a row of a table to a data location outside of the table's repeat nodeset. See the context() function for an example.
3. The itemlocation of items in table rows is interpreted relative to the top-left of the table row, not the top-left of the form. The top-left of each row is determined as follows:
   • Each row is set 3 pixels in from the left edge of the table.
   • The first row is set 3 pixels below the top of the table.
   • Each successive row is set 1 pixel below the previous row.

     By default, only 1 pixel of space is inserted between rows. As such, we recommend that you position the items in your rows to add the desired amount of additional space to the top of each row. For example, you might set each item in a row to have a <y> value of 2, thereby adding 2 pixels of space to the top of the row.

4. The itemlocation of items in table rows may reference items in the same row of a table, or items outside of the table. For instance, you might want to align an item in a row with a column heading. However, the itemlocation cannot reference containers (such as panes or tables) that contain that item.
5. The next and previous options in the table determine which items precede and follow the table in the tab order, but do not affect the tab order within the table.
6. When tabbing into a table, a forward tab places you in the first row of the table and reverese tab places you on the last row of the table. The first and last options determine which item in that row receives the focus.
7. Tab order within a table is determined by the next and previous options within the items in each row, combined with the natural order of the rows. When you are on the last item in a row and tab forward, you move to the first item in the next row. When you are on the first item in a row and tab backward, you move to the last item in the previous row.
8. When using computes with a table, the following restrictions apply:
   • Computes written within a row cannot reference elements in a different row.
   • Computes written outside a row cannot reference elements within a row.

     However, computes within a row of a table can reference elements outside of the table.

9. If the nodeset binding of the xforms:repeat is empty or contains non-relevant nodes, then the xforms:repeat provides a default of false to the table's visible and active options.
10. If the table is not visible, then none of the controls in the table will be visible, regardless of their states of visibility.
11. When working with tables, users will also need controls (such as buttons) that can add and delete rows. To do this, you must use the xforms:insert and xforms:delete actions. For more information about these actions, refer to XForms actions.
12. The size of a table is determined by the size of the items in the table. As such, the extent setting in the itemlocation option has no affect on the table's sizing.
13. The expandheight and expandwidth settings for the itemlocation option allow you to resize height and width of an items more precisely. This is particularly useful for resizing lines that are used to separate table rows and columns.
14. The layoutflow option allows you to control whether items are placed the vertically or horizontally within each row of the table.
15. The rowpadding option allows you to adjust the spacing between each row in the table.
16. The itemprevious is set as follows:
    • The table refers to the item that precedes the table in the build order.
    • The first item in the first row of the table refers to the table itself.
    • The item that follows the table in the build order refers to the last item in the last row of the table.
17. The itemnext is set as follows:
    • The table itself refers to the first item in the first row of the table.
    • The last item in the last row of the table refers to the item that follows the table in the build order.
    • The item that precedes the table in the build order refers to the table itself.
18. Do not use itemprevious to compute the location of an item after an table . Doing so can break signatures, as the items inside tables receive random scope identifiers at runtime. If you sign the form with a compute resolved to a random sid, the compute is locked to that random sid. If you then re-open the form, the items inside the tables are assigned new random sids, which do not correspond with the sid associated with the compute and break the signature.