Using a Notes Outline to control page navigation in a composite application 

Introduction

In this article you will learn how to construct a Notes Outline control that will allow the end user to navigate between pages of a composite application. The main idea is to configure the composite application to not show the default page navigator down the left side but replace that with a Notes Outline control embedded in a page. This will also give the composite application page navigation immediate role based access because visibility of outline entries can be controlled by the ACL.

This concept requires the use of the pagealias parameter of the CAI URL. This parameter was introduced in Lotus Notes 8.5.2 so this article is intended for versions 8.5.2 and above.

Creating the Outline

The first item we will tackle is the outline. We need to create a composite application by selecting File | Application | New from the Lotus Notes menu. We will then choose to create a new NSF based on the Composite Application Template.



Once the database is created we need to Launch Domino Designer and open the database in there. Once opened we will create a new outline under the Shared Elements item in the tree, we will name this outline "MyMainOutline":


In out outline we will create three different entries:

Page 1, set to URL action with a value of "cai://?pagealias=Page 1"
Page 2, set to URL action with a value of "cai://?pagealias=Page 2"
Admin, set to URL action with a value of "cai://?pagealias=Admin"

We will also put a Hide When formula for the Admin entry, this will disallow navigation to the Admin screen from the main UI:

Paste this formula into that section:

{code}
@IsNotMember("[Admin]";@UserRoles)
{:code}


If you want access control to be enabled you will then need to add the [Admin] role to your database ACL. This can be done from the Access Control dialog for our new database. Here I added a role and assigned it to myself:



The next step is to create a Page in the NSF that will house the Outline. We can not just show an outline in a composite, it has to be part of a page. Create a new page named "MainPage" and place the outline we created on the page. You can also put other things on the page to pretty it up.

Setting up the Composite

Creating the application

Now that we have a page with an outline on it, we can create the composite layout and add the page as a side shelf component. Open the application in the Notes client and select Actions | Edit Application from the top menu.


Once we are in the Composite Application Editor (CAE) we will start by editing some of the global application properties. You do this by clicking the context menu on the Page Navigator tab.


When the dialog appears, open the Advanced tab and add the two following keys and values.

com.ibm.rcp.useNavigator = true
com.ibm.rcp.navigationModel = custom

The useNavigator setting tells the CA subsystem that we want a navigation system and the navigationModel setting equalling "custom" tells it that we will provide our own page switcher.

Create the three pages

For our demo purposes we will just create three different pages and place a different component on each page to prove our the design. As in the outline we create before, create three pages named "Page 1", "Page 2", and "Admin". For this exercise place an Inbox component on Page 1, the Notes Calendar on Page 2 and a web browser component on the Admin page.

You will then go into the page properties and make sure the com.ibm.rcp.alias is set to the same values. In our case we use the same values but in general the alias can be different then the title of the page.

Adding the page navigator

Now in the CAE you can add your outline to the left side shelf. You will use the Add NSF Component wizard to accomplish this. The wizard can be launched from the CAE Component Palette:



When the dialog comes up you can give the component the name "Main Menu", you will then click the browse button to select our page from the current database. Next we will select from the wizard the current database and find the page we placed our outline control onto.


The component should now be added to you component palette. You can now drag the component over to the Left Side Shelf area in the CAE. It should look like this once you are done:


Save and exit the CAE, your application is now ready for use!

Summary

To summarize, we constructed a multi-page composite application that has its navigation control by another Notes based component (in our case an Outline on a Page). We used the pagealias parameter of the CAI url to control what pages would show in the application when an entry in the outline is selected. Since the pagealias URL can be used anywhere, we really could have created our navigator out of any technology. The beauty, as shown in this tutorial, about using an NSF based Outline is applying role based control to pages is very simple.