View Controls are an XPages feature to enable a web application developer quickly display data records, or documents, from a Notes database in a tabular fashion. The View Control provides many out-of-the-box features to make Web Applications rich and interactive. This article will show how to work with and use many of the View Control features.
The following topics are covered :-
- View Control Display Properties
- View Control Column Display Properties
- View Control Column Header Display Properties
The Example Application
The sample application used in the examples and diagrams 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 "How To Create a View Control" article in the XPages section on the Lotus Domino Designer wiki.
The following diagram may help with understanding the various parts of the View Control that will be referenced throughout this article.
Figure 1: View Control Parts
View Control Display Properties
You can give a View Control a View Title that will appear in the upper left hand side of the View Panel. It can be static or computed.
Add a View Title That Includes the Users Name
context.getUser().getFullName() + "'s Contacts"
to have the users name appear in View Title. See Figure 2.
Create a View Title
This will produce output like that shown in Figure 3 below.
Figure 3: Computed View Title
Note: The "View Title" is not the same as the "title" property for the View (see View Properties, All Properties). The title property, often called the "Advisory Title", is used to provide a small piece of extra information that is associated with a control. How the title is rendered is up to the browser but are typically displayed as a small pop-up window when the mouse hovers over a control, like a tool tip.
Add a Pager to a View Footer
Also, in the Display section of the View Properties, select "Show pager in footer", (see Figure 2 above). Note that there are several different out of the box "Pager styles" available, and there is also the option of creating a custom layout for your pager.
A Note on Facets
The View Title, the Pager in the View Header and the Pager in the View Footer are all View Control Facets. Facets are components that are sub-ordinate to the main component but are not necessarily in a parent-child type relationship. The View control has three Facets, headerPager, viewTitle, and footerPager. See Listing: 1.
Listing 1: View Control Facets
When you choose to show a title, or a pager in the header or footer of a View Control, Domino Designer automatically inserts those controls as facets. A subsequent article will focus on what facets are available in the View Control and how the user can modify the source to add more capability to these facets.
Change the Number of Rows per Page in a View
To limit how may rows can be displayed per page in a View Control, modify "Maximum rows per page:" in the Display section of the View Properties (see Figure 4) from the default value of 30 .
Figure 4: Set the Number of Rows Per Page
View Control Column Display Properties
The View Control Column element is the part of the View where the data is displayed. The View control provides a number of interesting and useful features to make creating applications with a View control simple and straight forward.
Note that the "Column Display Properties" is an area in the View Column section, see Figure 5.
Figure 5: Column Display Properties
Use a Check Box for Row Selection and Deletion
You can add a Check Box to any Column in the View Control so that, at run time, every element in that column will have a check box. It is set in the Column Display Properties, see the "Check box" field in Figure 4 above.
A Check Box on its own will not do much. One of conveniences that XPages offers is the set built in functionality to support commonly required tasks, for example, to delete the selected rows from the database.
Add a Button to the XPage with your View Control and change the Label: (in the Button Properties sheet) to something like "Delete Contact(s)". In the Button Events sheet, for the onClick Event, create a new Simple Action (see Figure 6 below).
Figure 6: Add Simple Action
For the Simple Action choose the Category: Document and set Action to "Delete Selected Documents" (See Figure 7a below). The "Delete Selected Documents" action requires a number or arguments, most importantly the name of the View Control the action is to operate on. In the example it is "viewPanel1" and Confirmation text: is set to "Are you sure?".
Figure 7a: Delete Selected Documents Simple Action
When the application runs, select a number of rows via the Check Boxes displayed in the ContactID column and click the the Delete Contact(s) Button. A confirmation will pop-up (See Figure 7b), click OK and the selected rows will be deleted.
Figure 7b: Select Rows to be Deleted
Use a Link to Open Detailed Row Data for Reading or Editing
Another commonly required task by application developers is the ability to select a row from a table of data and to open that record for editing, or just to be able to see any extra details. XPages View Controls provide a feature that enables data in fields to be presented as links so that that when clicked bring the user to a detail page for the row selected. This data can be presented in read-only form or it can be editable.
Enable this feature for any column by selecting the "Show values in this column as links" option in the View Column Properties sheet (see Figure 8 below).
Figure 8: Show values in this column as links
Notice that there is the choice for the mode the document will be opened in, Edit and Read-only. Figure 9 shows belows show the effect of opening in Read Only or Edit for the same page.
Figure 9: An Example of same XPage Document Opened in Two Different Modes (Read-Only and Edit)
Which Document to Open
There are three ways the XPages runtime uses to determine which document is to be opened.
1. specify the XPage to be opened in the View Control.
2. else the runtime will look for the Form field and an association with an XPage.
3. else the runtime will use the Form field content and append ".xsp".
To specify a specific XPage in the View Control that will be opened when the user clicks on a link set it in the Properties sheet for the View Control (see Figure 12 below).
Figure 12: specify XPage to open document
How It Is Done
Based on the options selected XPages automatically generates all information needed to open the document for the row. When the application is running in a web browser, hover the pointer over one of the fields in a View Column whose values have been set to be shown as links. Notice the URL that is generated at the bottom of the browser. After the main Notes application URL, the XSP page to be opened is specified and then this is followed by a set of name value pair parameters. The first parameter is the Document ID associated with the row of data from where the link was clicked. Then the mode the document should be opened in is specified, and then finally, the last parameter is the session ID. See Figure 13 below.
Figure 13: URL format for Links
View Control Column Header Display Properties
Most of the magic happens in the View Control Columns but there are two very useful pieces of functionality provided by the View Control Column Header,
- Column Sort, and
- 'Select All' Check Box
The following sections will provide more detail on how to implement both.
Make Columns Sortable
The following sections explain how to make a column sortable in a View Control.
Prerequisites - View Control relationship to Notes View
For sorting, there is a tight relationship between the View Control and the Notes View that is the Data Source for the View. Before being able to properly apply sorting options in the View Control, you must enable the base Notes View to present the underlying data in a sorted order. This is done via the Sorting tab on the Column Properties for the Notes View.
The first sort option relates to just having the data returned in an ascending or descending order (see Figure 14 below). Even if you provide no Sort option to the user, the data will always be returned in the order specified here.
Set the data to be returned in fixed order
The second sort option is to enable the View to provide the user the option to sort the data by clicking on the Column Header (see Figure 15 below). Whatever option (ascending, descending, or both) is chosen here will be reflected in the XPages View Control when the Sort column option is selected (i.e. up arrow icon for ascending, down arrow for descending, and both up and down arrows for both).
Enable the user to select different sort options
Note of course, if the data is initially set to be returned as, for example descending order, and you only select a descending sort option for the column header, then the data will always be presented in descending order, no matter how many time the user clicks the View Control column header.
View Control Properties
To make a column sortable in a View Control, select the "Sort column" option in the Properties sheet of the View Column Header (see Figure 16).
Make a View Control Column Sortable
Note that if the prerequisite sort option, Click on column header to sort (see Figure 15 above), for the base Note View is not enabled then sorting will not be enabled in the View Controls View Column Header either (see Figure 17 below).
Sort column option is not available in View Control is underlying view is not set up
At runtime, the XPages header for the column will be have small sort icons and the column header title will become an action link (see Figure 18 below). Clicking on the link sort the data.
Figure 18: Sortable Columns
Add a 'Select All' Check Box
A check box created in a View Control Column Header provides the ability to automatically select, or de-select, all the check boxes for all the rows in the corresponding View Control Column.
Before starting this step, verify that the ContactInfo View Control Column has a Check box, otherwise there would be nothing to automatically select. To enable this 'Select All' feature, select the "check box" option on the Properties sheet for the View Column Header (see Figure 19 below).
Figure 19: Enable 'Select All' Check Box in View Column Header Properties
Note (1) : When the Check Box in the Column Header is selected, only the rows that are visible are automatically selected. Rows in next or previous pages are not selected.
Note (2) : if a Column Header has a Check Box, and the corresponding Column does not, when an action is executed to perform an operation on selected rows the application will pop up with a warning to 'Please select one or more documents to delete.
At runtime, when a Check box in Column header is selected, all the Check boxes for the View Column on the visible page are automatically selected.
Figure 20: Check Box in View Control Column Header at Design Time and Run Time
See the following wiki articles for more information on working with View Column Display properties
Working with XPages View Controls - Computed Columns
Working with XPages View Controls - Display HTML
This article showed that the View Control contains many features that will be useful for everyday applications to make them feature rich and interactive, and that XPages facilitates this with little or no coding.
There are three main areas on a View control, the overall View itself, the Column area where the application data will appear and Column Header area where the label or title for the column data will be shown. Out of the box you get paging functionality and control over how many rows are displayed per page, and how the data can be sorted. You get the ability to select individual rows have and have common operations performed on this data without any programming.