Notes developers will be familiar with the various options available in basic Notes Views for presenting data stored in several Documents in a structured and tabular fashion. Notes Views also provide two mechanisms to display data that does not come directly from one of the fields defined in a record belonging to a Form stored in the database, Simple Function and Formula.
In XPages, almost everything is computable, so it is no surprise that the XPages View Control also provides a number of mechanisms to compute values for the data that is to be displayed in the View Column of an XPage View Control.
This article will describe how to :-
- Dynamically Set Which Field (or Data Column) is used in a View Column
- Create a Calculated Value for the Data of a View Column
The table below show the three options available to a Notes developer when displaying Notes View column data. The Formula option is the method available for creating computed or calculated columns.
Table 1: Notes View Column Value Display Options
Display is set to Field.
The data for this View Column comes directly from the a field belonging to the Form the View is based on.
Display is set to Function.
The data for this View columns comes from one of the many pre-defined functions that can provide information about the Document in each row of the View.
Display is set to Formula.
The data displayed in this View column is the result of the expression used to create the Formula.
The example here appends three strings, two of them coming from Fields in the Form the View is based on.
XPages View Control Computed View Column
There are four sub-sections in the section :-
1. The Example Application - brief description of the simple Contacts application that is used in the article to help explain the techniques the are being discussed
2. Static Declaration - a quick review of the static options for View Columns is shown and then
3. Dynamically Set Which Field (or Data Column) is used in a View Column - how to compute the column that provides the data for the View Column.
4. Create a Calculated Value for the Data of a View Column - how to compute data for a View Column
The Example Application
The sample application used in the examples below is a very simple Contacts application that consists of two pages, one to allow you enter and edit the details of a contact and the other that displays the list of contacts in table. The contact details consists of the following fields ID, first name, last name, e-mail address, and contact information. The contact information is more verbose multi-line data, containing extra contact details and is stored in hCard format. The steps on how to create the sample contact application are contained in the following two articles in the XPages section on the Lotus Domino Designer wiki.
- How to Create a View Control
- Working with View Controls
The sample application created in the two articles above is used as the starting point in the examples below.
By default, each column in the View Control is associated with a column from the Domino View. After the View Control has been created, the developer can modify the Data properties of the View Column via the Data Section of the Properties sheet for the View Column. See Figure 1(b). This is declarative and not dynamic.
Figure 1(a) and 1(b): Static Declaration of Data Columns associated a View Column
(a) Design View of the selected View Column
(b) Data Section of the View Column Properties sheet for the selected View Column.
Dynamically Set Which Field (or Data Column) is used in a View Column
This section describes how to compute the column that provides the data for the View Column.
It is worth pointing out at this stage that the only View Column properties that can be set in the Data section of the View Column Properties sheet are the three properties that control which column from the Domino View (and it can be a Field, Simple Function or Formula data column) is displayed inside the selected View Column. For more data related properties see the next section.
As can be seen from Figure 1(b) above, the View Column: property can be computed, as indicated by the diamond shaped Computed property menu button. To use a computed value for the View Column property, enter an expression that will return the name of the data column that is to be displayed.
Note: the Content Type for the View Column is set to HTML, therefore, whether the email address or the hCard formatted data is returned, both will be interpreted as HTML. For the purposes of this sample application it is assumed that the email address will never contain any HTML tags or reserved characters.
Figure 2 (a) and 2(b): Dynamically set which Data Column to show in the View Column
2(b) The same property can be set dynamically in the All Properties section of the View Column Properties sheet. Note that the property name id ColumnName.
A button can be added to the page with an action to change the sessionScope.LongContact variable that is used in computed code for the View Column so that the data displayed in the fourth column with the ContactInfo Column Header changes each time the Short/Long button is clicked. See Figure 3 for example output of a View Column changing dynamically.
Figure 3: ContactInfo data changes when the Short/Long button is pressed
The label on the button is also computable and changes accordingly.
The columns Last Modified (using 'Last Modified' Simple Function, see Table 1) and Full Name (using 'FirstName + " " + LastName Formula) are taken directly from the Domino View, so Simple Functions and Formulas (see Table 1) can be incorporated into an XPages View Control. For Date and Time values change the Display type property in the from String to Date/Time in the Data section of the View Column Properties sheet.
Create a Calculated Value for the Data of a View Column
This section shows how to create a computed or calculated column similar to the Formula functionality (see table 1). Again, this example will take the data from the FirstName and LastName fields of the current row to create a new computed, or calculated, column. Note that the formula in used in a View will be part of the View document in the database and executed during the view query, whereas the XPage computations will occur at render time.
As noted in the previous section the properties shown in the Data section of the View Column Properties sheet only affects which data column of the associated Domino View is to be shown in the View Column. All steps in this section will require working with the All Properties section of the Properties sheet.
Before continuing with the View Column, a property needs to be set for the View Control. View Controls and the Domino Designer for Eclipse UI automate almost all of the work in retrieving data from a Notes Domino database. Unlike the DataTable and the Repeat Controls, by default, a variable that references the current row in the ViewControl is not published automatically to enable programmatic access. To make this var
property available, set a value for the var
property in the All Properties section of the Properties sheet of the View Control. For example, the variable that will be used to represent a single row in the View Control is contactRec
Figure 4: Set the var property for the View Control
Back to the View Column. Select a view column whose data is to be computed and open the All Properties section of the Properties sheet for the View Control. Note that in the data
tree, the value
property can be a computed property. See Figure 5.
Figure 5: Data value computed property for selected View Column
The variable contactRec
created previously is published in the XSP page. It is an object of type NotesXspViewEntry
contactRec.getColumnValue("FirstName") + " " + contactRec.getColumnValue("LastName")
to dynamically compute the full name of the contact in the current record to achieve the same result as the Formula in Table 1 above.
Figure 6: JavaScritpt expression to compute a value for the data in the selected View Column
And when the XPage is run, the output is as shown in Figure 7.
Figure 7: Example showing data computed in an XPage View Control returning same result as column based on Notes View Formula
Another technique that makes use of computed columns in XPages is demonstrated in the excellent article from Nathan that shows how do an @DbLookup in a view column -- otherwise known as "can't do JOINs" :-