This is a tutorial that will show, step by step, from start to finish, how to create an XPages View to display data stored in a Notes database.

The tutorial is based on a very simple contact application that stores details such as name, email, address and other contact information.

In this sample application, the contact information is stored in hCard format. The application will take in the individual user details that are entered, compute the hCard data and save it to the database. Note that it may not be desirable to include presentation markup directly with the data, another article "Working with View Controls" shows how to separate the presentation from the data and compute it dynamically for display.

By the end of this tutorial the reader will be able to create a simple yet complete XPages web application. The application will provide a solid foundation and understanding for modifying and using Views and can be used as the basis for enhancements that will be shown in other tutorials and "How To" articles about View Controls. See Next Steps at the end of this article.

The tutorial tries to assume nothing and starts right from the start, no predefined Notes Forms or Notes Views.

The Tutorial Steps

The following outlines the main steps of the tutorial :-

Step 1 - Create a new Application
Step 2 - Create a new Notes Form
Step 3 - Create a new Notes View
Step 4 - Create a new XPage
Step 5 - Add a Save Button
Step 6 - Add a Save Event to the XPage
Step 7 - Add button to make a Read-Only Document Editable
Step 8 - Test the Page and Add Data
Step 9 - Create a new XPages View Control
Step 10 - Link the Two XPages

Background

Core controls ( e.g Button, Label, inputText, etc.) are common controls that appear as single entities in a page or custom controls. A View control is classed as a Container Control, that is, it is a control that is more complex than core controls because they are designed to contain other controls.

A View will appear in a web application as a rectangular portion of that page that contains rows and columns of data. The data comes from a Data Source that is associated with the view.

Step 1 - Create a new Application

Create a new blank XPages application for this tutorial.

1. Launch IBM Lotus Domino Designer for Eclipse (DDE)


2. Choose File -> New -> Application


3. See “New Application” Dialog


4. Leave Server as “Local”.


5. Set Title to “ContactApp”. File name will auto-populate to “ContactApp.nsf”.


6. Click OK.

Step 2 - Create a new Notes Form

This turorial is based on using a Notes database to store the data. A basic Notes Form is needed to enable the XPages contols view and manipulate the data fields for a particular record. The Data is stored in a Notes document and the Form helps define the structure of the data in that document. Create a new Form with seven fields to support the sample contact application.

1. Right-Click on the Forms design element and select “New Form...”


2. Set the Name to “contact”


3. Click OK


4. On the Form, right-click and select “Create Field...” (or choose Create -> Field)


5. Set Name to ContactID, and leave Type as Text and Editable.


6. Close the Field dialog.


7. Repeat the previous 3 steps for the following six fields (FirstName, LastName, Email, Address, Website and ContactInfo).


8. Save the Form (Ctrl+S)

Figure 1: New basic Notes Form

Step 3 - Create a new Notes View

A Notes view provides a way to access Notes data in a tabular fashion. XPages controls can leverage Notes objects such as Forms and Views. Create a Notes view using the following steps.

1. Right-Click on the Views design element and select “New View...”


2. Set the View Name to “contacts”


3. In “Selection conditions” select “By Formula” and enter SELECT (form=“contact”) - not really needed since we only have one form. The default is SELECT @ALL


4. Click the green tick to verify the syntax.


5. Click OK


6. Open the new contacts view.


7. Close the View Properties dialog.


8. Select the first column with the '#' (pound sign)


9. Right-click on the column and select Column Properties


10. Change the Name to ContactID


11. In the sorting tab (the second tab)


12. Set Sort to be Ascending


13. Select “Click on column header to sort” and choose “Both”


14. Close the Column properties dialog.


15. In the Objects tab, select the new column ContactID, set Display to Field, and select ContactID.


16. Click back on the view area, right-click and select “Append New Column...”


17. Right-click on the column and select Column Properties


18. Change the Title to “FirstName”


19. Close the Column properties dialog.


20. In the Objects tab, select the new column FirstName, set Display to Field, and select FirstName.


21. Repeat the previous 5 steps for the following 3 view columns, LastName, Email and ContactInfo (choosing the matching form field of course).


22. Save the View.

Figure 2: New basic Notes View

Step 4 - Create a new XPage

1. Right-Click on the XPages design element and select “New XPage...”


2. Set the XPage Name to “contactDetail”.


3. Click OK


4. In the Properties Tab – select Data


5. Click the “Add” drop-down list and select “Domino Document (this document will be based on the Form created previously).


6. In the Data Source: Domino Document area, select “contact” from the Form drop down list (it should be the only one). Note the Name of the data source is document1.


7. Save the XPage to save the data source changes.


8. Click on the XPage design area to make the XPage the focus.


9. Open the Data Palette. See document1 listed as a data source.


10. Multi-select all the fields (except Contact Info) and drag them onto the XPage. Note that the fields will be in alphabetical order. By using a multi-select and dragging, Designer will automatically create a table to store the labels and edit boxes that are bound to the fields of the contact form. The fields can be re-arranged later by right-clicking on the table and selecting “Insert Row Above”, and then dragging the labels and edit boxes to the appropriate location. When finished, right-click on the table again and selecting “Delete Row(s)”, and finally clicking OK to confin the number of rows to be deleted.


11. Save the changes to the XPage.

Step 5 - Add a Save Button

Before starting, make sure the cursor in the Design tab is sitting below the table.

1. Open the Controls Palette.


2. Drag a Button control to the Design tab, it will appear below the table.


3. Go to the Button Properties tab and change the Button Label: to “Save”.


4. In the Options area, change the Button type: to Submit from the drop-down list.


5. This page will be used for displaying the Contact details in an 'Edit Mode' and a 'Read Only' mode. In the 'Read-Only' mode, there would be no need to display the Save button, if fact it would probably be confusing. If the document being displayed is in read only mode then don't display the button.


1. Click on the computed property menu button for the Visible property (it is the blue diamond beside the Visible label) and select “Compute value...” and enter document1.isEditable() where document1 is the name of the data source for the page so that the button is only visible when the document that is being displayed on the page is editable.


2. Click OK.

Step 6 - Add a Save Event to the XPage

The next set of steps will add an action to be performed when the data in the contactDetail XPage is about to be saved.

1. Select the XPage (by clicking an area outside of the table with the edit boxes).


2. Select the Events tab.


3. Expand the Data element in the tree menu.


4. Expand document1.


5. Select querySaveDocument


6. Click on the "Add Action..." button


7. See the "Add Simple Action" dialog.


8. Set Category to Basic


9. Set Action to Execute Script


10. In the Condition text box enter the code shown in Listing 1 below (click on the Script Editor button to enter the code and click OK when finished).


11. Click OK

Step 7 - Add Button to make a Read-Only Document Editable

1. Open the Controls Palette.


2. Drag another Button control to the Design tab, it will appear to the right of the existing Save button.


3. Go to the Button Properties tab and change the Button Label: to “Edit”.


4. This time, two things need to happen:


1. the Edit button should only appear if the document is in 'Read-Only' mode.


2. when the user clicks the Edit button, the document should change to Edit Mode.


5. Make the Visible property computable.


1. Click on the computed property menu button for the Visible property (it is the blue diamond beside the Visible label) and select “Compute value...” and enter !document1.isEditable() (note the negation mark '!' at the start) so that the button is only visible when the document is not editable, i.e. read-only.


2. Click OK.


6. Change the document mode to Edit when the Edit button is clicked.


1. Open the Events tab for the Edit button


2. Verify “Simple Actions” is selected and Click the “Add Action” button.


3. See the Add Simple Action dialog.


4. For Category: select Document


5. For Action: select Change Document Mode


6. In the Arguments for this Action area, for Document mode: select Edit Mode


7. Click OK


7. Save any changes (Ctrl+S)

Figure 3: XPage based on a Notes Document

Step 8 - Test the Page and Add Data

If this is a local application, when testing pages, the built-in web server will require some access control permissions to be set. The simplest solution is to grant all permissions to the Default user (this is not recommended for production systems).

Change the Access Control List

1. Right-click on the application name and choose Application -> Access Control


2. See 'Access Control List to: ContactApp' dialog


3. In Access Control List select Default.


4. Under Attributes, for Access, select Manager from the drop down list and also select Delete Documents as an additional access right.


5. Click OK

Figure 4: Application Access Control List

Preview the XPage in a Web Browser

1. Select the contactDetail XPage by clicking on the XPage design area (otherwise ContactApp.nsf file will be previewed and not contactDetail.xsp as desired)


2. Choose Design -> Preview in Web browser -> Default System Web Browser


3. Enter some dummy data


4. Note that the Edit button is not visible.


5. Click Save (Note that a blank form should appear after a successful save).


6. Close the Web Browser.

Figure 5: Contact Details Form Preview

Step 9 - Create a new XPages View Control

Create the View Control and bind it to a Domino View (the Note View created previously)

1. Right-Click on the XPages design element and select “New XPage...”


2. Set the XPage Name to “contactList”.


3. Click OK


4. Open the Control Palette and look in the Container Control section for a View control and drag it onto the design page.


5. See “Select Data Source for View” dialog.


6. For Show data from: select “Domino View”


7. In the Domino View area, for View: select “contacts” (it should be the only one). Note that the view columns appear automatically.


8. Leave Data source name: as “contacts”


9. De-select the Email view column and leave all the other view columns selected.


10. Click OK.


11. Save all the changes (Ctrl + S). The view control should appear in the design area as shown in Figure 6.

Figure 6: The View Control in Design mode

Modify Column Width

As the ContactInfo column is a textArea, is might be useful to limit the width of this column.

1. Select the View, open the View Properties sheet and set Units: to Percent and Width to 50.0.


2. Select the ContactInfo column, open the View Column Properties sheet and set Units: to Percent and Width to 25.0.


3. Save all the changes.


4. Preview the view (Design -> Preview in Web browser -> Default System Web Browser) in action now and it will show the contact entered in the previous step.

Figure 7: Contact Application View Control Preview

Step 10 - Link the Two XPages

The following step shows how easy it is to add navigation to an XPage, improves the usability of the two pages and finishes the Contact application to a level that it can be used as the basis for the tasks outline in the Next Steps section at the end of this article.

Link the View XPage to the Detail XPage

1. Open the contactList XPage.


2. Drag a Button Control from the Controls Palette and place it below the View.


3. In the Button Properties sheet change the Label field to "Add Contact".


4. Open the Button Events sheet.


5. Ensure Simple Actions is selected.


6. Click Add Action...


7. See the Add Simple Action dialog


8. Set Category: to Basic.


9. Set Action to Open Page


10. In the Arguments for this Action area,


1. Set Name of page to open: to contactDetail


2. Set Target document: to New document
11. Click OK


12. Save the Changes

Link the Detail XPage to the View XPage

1. Open the contactDetail Xpage.


2. Select the XPage element.


3. Open the XPage Properties sheet.


4. Set Next page (success or cancel) to contactList


5. Save the changes.

Test the Changes

1. Select the contactList XPage.


2. Preview the page in the default system Web Browser.


3. Click Add Contact


4. See the contactDetail XPage and fill in some dummy data.


5. Click Save


6. See the contactList XPage, but note that the View now contains the new entry.


7. Close the Web Browser.

Figure 8: Test the Change in the Contact Application

Summary

This article shows how to create an XPages View Control that provides data from a Notes database using a basic Notes View to define the columns. It builds a tutorial around a simple Contacts application and covered defining data sources, both Domino Views and Domino Documents, navigation between XPages, and actions to be performed when Buttons are clicked.

Next Steps

Enhance the View Control with row selection, add actions to delete selected rows, add sortable columns, and display column data as HTML formatted with CSS stylesheets, by following the steps shown in "Working with XPages View Controls" and "Working with XPages View Controls - Display HTML" on the Domino Designer Wiki.

Resources

See the XPages online help available in Domino Designer for Eclipse for more details on creating with XPages View Controls.

Sample Code

 



Listing 1: XPage Save Event Code 



var g = getComponent("FirstName1").getValue(); 

var f = getComponent("LastName1").getValue(); 

var e = getComponent("Email1").getValue(); 

var w = getComponent("Website1").getValue(); 

var hCard = ""; 



hCard = "
" 

+ "
" + g + " " + f + "
" 

+    "
" 

+       "
"  + g + "
" 

+       "
" + f + "
" 

+    "
" 

+    "
" + e + "
"       

+    "
" + w + "
" 

+ "
" ; 





document1.getDocument().appendItemValue("ContactInfo",hCard); 

return true;