The table wizard will only get you so far, and sometimes you need a little more control over the functionality or look and feel of your table. That's when it's time to roll up your sleeves and dig in to the XForms table widget. XForms tables (also known as an XForms Repeat object) are a very powerful tool that allow you to display repeating data in many different ways. The goal of this tutorial is to help you understand how to build a simple XForms table, from scratch, without the help of table wizard that is provided with the Designer. You should have some basic understanding of XPath, XML and you should understand how to build XForms tables with the table wizard.
1. Build your XForms instance.
Building a table involves 3 major components: defining your data structure, building a single row, and connecting your row to your data structure. When the form is rendered, the table will look at the data structure, and the number of rows you've defined there will determine how many times the form should repeat the row you designed. So to get started, we should create our data structure first.
Tables should always be at least 3 levels deep, excluding the root node of your XForms data instance. Tables always follow the pattern outlined here. You can rename your table and row elements whatever you like, however all rows and their child (column) elements must share the same names.
Create a table structure like this one in your form. You can create it either by using right-click commands in the Instance View in the Designer, or by going to the Source tab and pasting the following code anywhere in between the <
xforms:model> tags (note that the code here is its own instance and therefore must be pasted outside any other already existing data instances). Tables don't need to be in their own exclusive data instances. You can put a table structure anywhere in another existing data instance.
<xforms:instance id="formData" xmlns="">
<row> <!-- In this case, the second row and last row, so when the form is rendered, the table will show two rows. -->
2. Create your basic table object.
The goal of this tutorial is to understand how to create custom built tables without the use of the wizard. So we need to create a table object on our form from the advanced palette, since we don't want to use the table wizard. First you should make sure you are in the Advaned Lotus Forms Designer perspective. To do this, click on the "Window" menu, then choose "Open Perspective" then choose "Advanced Lotus Forms Designer". Now that you're in the advanced perspective, you can access the Advanced Library section of the palette. Within the palette you will need to click on the Advanced Library bar to expand it. Now to create a table, click the drop down right beside the Table (Repeat By Wizard) tool and choose Table (Repeat). Now you can click anywhere in your form canvas to create a table.
3. Configure your table.
The table needs to be linked to its data structure before anything interesting will happen. To do so we must put an XPath statement into the nodeset property of the table. The nodeset is the most important part of your table because this XPath ref determines what data drives your table.
First, get the XPath reference to the table. Your XPath statement needs to select all (2 in this case) row elements. So the xpath you would use here would be:
Reminder: To get this XPath you should use the Instance view in the designer. Expand your data elements until you find the first row element. Right click on it and select "copy reference". This copies an XPath reference to the row to your clipboard. It's important to do it this way because it avoids mistyping your reference.
If you have trouble with this concept you may want to follow an XPath tutorial (there are many free ones available online
Next, we will paste the XPath reference into the nodeset property of the table. To do this, first select your table object, this will cause its properties to be shown in the Designer's properties view. In the properties view, under XForms, you will see a nodeset property. Paste the XPath reference there.
4. Design Your Prototypical Row
Ok, so now we've got an empty table which should be showing two rows. We need to add some fields or other widgets into the table before it's actually useful. What we're doing here is designing a single "prototype" row, which all rows in the table will be based on when it's actually rendered in the running form.
Let's start by adding a field. To do this, go to the advanced palette and select Field (Input). Drop the field item inside your table. Now we need to link this field to our data by indicating which "column" element in the table data structure should be linked to this field. In our example data structure, we have a <
name> and <
age> element. Let's use the name element for this field.
To link this field to the name element, we need to put an XPath statement into the ref property of the field. We need to understand an important concept here, which is the concept of XPath context
. Because the field is inside the table, it inherits the context of the table. That means that the XPath ref we write here must be relative to the context, so in this case the XPath for the field should be
Filling the ref property in the properties view for the field should look like this.
You may be wondering, why wouldn't you use absolute XPath?
The answer is that if you did that, the XPath will select the name element in the first row, and use that data in EVERY row of the table. Try it out! By using the relative reference, the name element will be selected for the current row in each row of the table that is rendered, which is what we want.
Now you can similarly add a second field for the <
age> element in your table. Once you've done this and aligned the fields as you like, check your form in the preview window. You should see two rows! Now I'd encourage you to play with your data model to understand what drives the table. Try adding or removing <
row> elements. Try adding or removing the <
name> or <
age> elements in the <
See the attached form for an example of what your form should look like after completing all the steps.
You can read more about this topic in this follow up article
which shows how to create add/remove row buttons.