xforms:insertAdded by IBM on August 8, 2013 | Version 1 (Original)
|Adds a row of elements to a table. This function copies a row of elements in the data model, then inserts the copy in the desired location in the data model. Once the copy is inserted in the data model, the table's repeat creates corresponding items that are displayed to the user.
Table 1. insert parameters
<xforms:insert event nodeset="nodeset binding" at="at" context="context" origin="origin"
<xforms:insert nodeset="nodeset binding" at="at" context="context"
|event||string||The XForms event that triggers the action. |
|nodeset binding||special||Defines the node to copy. If multiple nodes match, then they are all copied. Also defines where to place the copy - it is placed into the data model as a sibling of this node. Use the nodeset binding if you are copying a node that is already in the table, and are placing the new node in the same table.
If you want to copy a node that is not in the table, use the origin attribute. This overrides the nodeset binding for this purpose.
If you want to place the copy in a table that has no rows, use the context attribute. This lets you point to a parent node rather than a sibling node, and overrides the nodeset binding for this purpose. The new node is create as a child of the context node, and is useful for tables that begin empty. In this case, once the first child is created, the nodeset binding is still used in conjunction with the position and at attributes to determine where additional rows are placed.
|at||string||An index number that sets the target row. The copy is placed either before or after this row in the table, as defined by the position attribute. Indexing is one-based, meaning the first row is row 1, the second row is row 2, and so on.|
|context||string||Defines where to place the new node. This allows you to define a parent, to which the new node is added as a child. This is useful if you need to add rows to an empty table, and overrides the nodeset binding for this purpose. If a parent is provided, the nodeset binding is still used in conjunction with the position and at attributes to determine where additional rows are added to the table.|
|origin||string||Defines the node to copy, and overrides the nodeset binding for this purpose. This is useful if you want to copy a node that is not already in the table (for example, a template node that is elsewhere in the form).|
|position||string||Defines whether the new nodes are inserted before or after target row. Defaults to after. The target row is defined by the at attribute.|
Example This example assumes you are working with a purchase order form that includes the following data instance:
This data instance includes a single <row> element. This is the "template" row for the table. As such, it is never used to store data. The purpose of this row is to provide a template that is copied when adding new rows to the form.
Since the data model begins with only one row, and that row is invisible to the user, we also add an xforms:insert to the data model. This insert is triggered when the form is first opened, once the XForms model is completely built. It uses the last function to determine whether there is only one row in the table. If there is, it add a new, blank row. This ensures that the table always begins with one blank row that the user can see.
The xforms:repeat that creates this table must also exclude the template row, as shown:
nodeset="order/row[last()=1]" at="1" position="before"/>
In this case, the nodeset includes all rows that are not in the last position in the table (which would be the template row). This ensures that the template row is never included in the table itself, and is never shown to the user.
To add more rows to this table, you must create a control (such as a button) that the user can click to trigger another xforms:insert action. You also need to add some other actions to this control account for special cases. The following button illustrates this:
In this button, the first action is the xforms:insert. This insert uses the index function to determine which row of the repeat (called orderTable) the cursor is on, then adds a new row after the row with the focus.
The next action is an xforms:setfocus, which resets the focus to the table. This is necessary because when the user clicks the "Add Row" button, the focus shifts to the button, so we put it back to the table.
<xforms:insert nodeset="order/row" at="index('orderTable')"
- When adding a row, the index for the xforms:repeat is automatically updated to point to the row that was just added.
- When processing the data model on the back end, make sure that you also exclude the template row. Otherwise, you will include a row of blank data in your results.