Getting started - XPage enabling an existing Notes client application 

Table of contents | Previous Page | Next Page

In this section of the Redbooks wiki, we will build a basic input form for creating Document Library documents.

Creating the Document Library database

Create a new database based on the Document Library template:



Make sure you uncheck "Inherit future design changes" to avoid that your developments would be overwritten by a design refresh.
The defult ACL set-up should be fine.

Creating a custom control

In order to build the web version of the Document form, we will
- create a custom control that will contain the form fields
- create an XPage that will include this custom control


Create a new custom control and call it ccFormDocument
In the data palette, define a data source of type Domino Document and call it dominoDoc:

Defining a data source

There are several ways to define a data source in a custom control or XPage: 1. Via the data palette 2. In the custom control/XPage properties via the Properties view, on the Data tab 3. On each UI Control individually, via the Data tab in the UI Control properties The first way is the easiest when creating a new custom control/XPage that needs several fields from the same data source (form or view).

From the data palette, select the fields "Subject", "Webcategories" and "Body" and drag them into the editor. Make sure the "Select controls dialogbox" option is enabled before doing this:



This option will make a dialogbox display with options to define data types of the dragged fields. If disabled, the data fields will be directly dropped in the editor as controls of the type "Edit Box".

In the controls dialog box, adjust the field labels of "Webcategories" and "Body" and change the type of the Body field to "Rich Text".
Also, check "Add submit button to generated code".




After pressing Ok, the controls are added in the editor, and our basic form is ready

Select Data Bound Controls dialog

This dialog automates various tasks which otherwise would have to be done manually: Create data controls for the fields and perform data binding for each control Create field label controls and link them to the corresponding field ("select target control" in the label properties) Add a submit button, which includes a onclick event handler to submit the form. This becomes more clear when you have a look at the source code view: <xp:button value="Submit" id="button1"> <xp:eventHandler event="onclick" submit="true" refreshMode="complete" immediate="false" save="true" id="eventHandler1"> </xp:eventHandler> </xp:button> The first way is the easiest when creating a new custom control/XPage that needs several fields from the same data source (form or view).

Save and close the custom control.

Creating the XPage

Create a new XPage and name it formDocument.

From the Custom Controls palette, drag the ccFormDocument custom control into the XPage.
Save the XPage and preview it in the web browser.

The result is a simple input form with a Submit button.

Enter some data in the fields and submit the form.
You will notice that, after submit, a new blank form is opened again. This is the default behaviour of an XPage after submitting: the same XPage is opened.

Verify the result in the Document Library application in the Notes client: the newly created document is stored in the database as main document. You will notice that the category field is empty. This is because we bound the Tag control to the Webcategories field, instead of the Category field. This is nothing to worry about now, as we'll handle that later on.

Managing attachments

With this basic form, we can create documents with rich text content, but we cannot add attachments.
XPages provide controls for uploading and viewing attachments.


Open the custom control ccFormDocument
Insert 3 table rows above the bottom row of the data table (=the one with the submit button).
Leave the first row blank.
In the second row add
- a file upload control in the second column (drag it from the controls palette), and name it fileUpload
- a label (drag it from the controls palette) in the first column with as label value "Attachments: " (without quotes) and target control name fileUpload
On the data tab of the upload control properties view, select "Simple data binding" with data source "dominoDoc" and bind to "Body".

In the third row, add a file download control.
In the download control properties, check the boxes "Hide if no attachments" and "Allow delete"
On the data tab of the download control properties view, select "Simple data binding" with data source "dominoDoc" and bind to "Body".

The data table in ccFormDocument now looks like this:



Save your changes and preview the XPage formDocument. Enter a subject, a description and an attacment. Submit the form and verify in the Notes client. As you see, the document contains both the description and the attachment in its body field.


Binding mutiple controls to a single data field
In general, you cannot bind mutiple controls to a single data field. For example, if you would create two Edit Box controls and both bind them to the Subject field on dominoDoc, only the value of the last Edit Box would be saved in the document.
File upload controls make an exception to this, in combination with rich text controls. You can create a rich text control and a file upload control and bind them to the sale data source (a rich text field on the underlying form), and both of their data will be stored in the rich text field. Also, mutiple upload controls can be added on the XPage and can be bound to the same data field.

Notice that upload controls in XPages store their value differently than with traditional Domino web applications. In traditional applications, the attachment is not stored in a rich text field (as there is no data binding with a field).

Displaying runtime errors

Chances are that something went wrong while previewing the XPage in the above steps, for example because you forgot a step within the sequence, and you got a runtime error when viewing the XPage in the web browser. By default, the displayed error is very vague and almost impossible to trace.
If you don't know what I'm talking about, add a computed field custom control to ccFormDocument and give it a severside javascript value, for example this.runtimerror(). This meaningless and will generate an error for sure.
When you then preview the XPage, a blank screen will appear with the message "Http Web Server: Command Not Handled Exception".

In XPage applications, the way errors are displayed can be configured:
In the Applications Navigator, go to the "Application Properties" design element of the Sample Document Library application.
In the Application Properties, click on the XPages tab.
Under "Errors and Timeouts", the field "Error page" is set to "Server Default" and "Display default error page" is not checked:



Check the box "Display default error page".
Save and close the Application Properties and try to preview the XPage again.
The cause of the runtime error is now much easier to find:

Displaying documents in a view

So far, we are able to create simple documents via the web. But we don't have an interface to existing documents yet.
In this topic, we will create a simple Notes-style view from which we can open existing documents.


Create a new XPage and call it "viewAllDocuments"
Create a new custom control, called ccViewAllDocs
Define a data source in the custom control of type DominoView. Select the view "AllDocuments - ($All)". Name the data source "dominoView"
Drag and drop the columns "Topic" and "Date" from the data palette into the custom control edit area.
Make the column "Date" the first column, by dragging it above the Topic column in the outline view:



Select the entire view (click on it in the outline view) and adjust it's properties: set the view width to 100%:



Select the Topic column in the outline view and in the Properties, Column Display Properties, enable the option "Show values in this column as links" with Document open mode set to "Read-only".

Save the custom control.
Open the Xpage viewAllDocuments
Drag ccViewAllDocs in the edit area and save and preview the XPage

The result is a simple view of the existing documents. The subjects are displayed as links, but clicking in them returns an error (Item Not Found Exception). This is because no interface has been specified yet for displaying existing documents.

Linking the form with the XPage

So far, we have built an input form to create new documents and a view to display a list of existing documents.
Now, we need to assign a web interface to existing documents which were created with the Document form:


Open the Notes form "Document" in Designer (yes, our good old existing Notes form) and display the form properties info box.
On the Defaults tab (=second tab), under "On Web Access" set the value of "Display XPage instead" to "formDocument.
Save and close the form.

If you now click on a link in the XPage viewAllDocuments in the browser, the corresponding document will open with the XPage formDocument.

Linking an XPage with a form

An XPage is linked with a Notes form in two ways: 1. Via data binding: if the data source is of type "Domino Form", and the default action is set to "Create new document", a new document will be created at submit and an item "form" with the form name will be added. 2. In the form properties. Since mutiple XPages can be linked with the same form as data source (and each XPage can have several data sources), an additional defintion is needed to specify with which XPage existing documents need to be opened. This is done in the form properties,as demonstrated above.

Completing basic navigation between form and view

Now, we are able to create new documents and view and edit existing documents. In order to have a basic, workable application, we need to finalize navigation:

• define an application entry point
• provide a button to create new document
• return to the view after a document has been submitted

Application launch options

When the Document Library database is launched in the web browser (=root database url: http://hostname/path/database.nsf), the application's old school web interface is displayed, rather than one of our XPages. This is normal, since we still need to tell our application to open in a different way:

Open the Application Properties design element, and go to the Launch tab.
Set the web launch options to open a designed XPage: viewAllDocuments.
Save the Application Properties and open the database url in the browser to see the result.

New document button

From the all documents view, we want to be able to create new library documents. This will be achieved by adding a button "New" on top of the view:

Open the custom control ccViewAllDocuments and drag a Panel container control above the existing view panel. Give the panel a name, "actionBar".
From the controls palette, drag a Link control into the actionBar panel and give the link a name "actionNewDoc" and a label "New document":




In the Events view, add a simple action: Open Page. Name of the page: formDocument. Target document: New document.
Save the custom control and preview the result in the browser. New documents can now be created from the All Documents view.

Return to the view after submit

Finally, we need to tell the XPage to return to the view of all documents after submit, instead of returning to the same page:

Open the XPage "formDocument" and go to the first tab, "XPage" in the XPage properties view. In the field "Next page (success or cancel)" change the value "Same Page" to "Previous Page":



Save the XPage.

Defining page navigation after submit

The target page to be displayed after submit can be defined either at XPage level (as in our example), or at Submit button control level. In the above example, the same result would have been achieved by adding a second simple action to the submit button, which opens the previous page. In that case, the control level navigation would override the globally defined navigation. In the above example, selecting "viewAllDocuments" instead of "Previous Page" as option for "Next page (success or cancel)" would have given the same result. But "Previous Page" is more generic: when more views will be created, this option will return the user to the view he was in prior to opening the form. Just be aware that "Previous page" doesn't work in case the opens the page url directly in the browser (for example, when he added it as a favourite, or when he clicks on the url link in an e-mail). The next page can be made conditional to handle this (click on the diamond to compute the next page).

Summary

In this chapter, we have created basic form and view functionality, comparable to traditional Notes client applications. Basic XPage concepts have been introduced, including data binding and navigation.
The next chapters will focus on layout and form enhancements, revealing the power of XPages as a platform for rapidly web enabling existing Notes client applications.