Create the website layout - XPage enabling an existing Notes client application 

Table of contents | Previous Page | Next Page

In this section, we will create a basic website structure with various website components (header, footer, navigation, etc...), and we will apply styles to our website.

We will provide our application with the look and feel of IBM's OneUI layout, as described in the IBM Lotus User Interface Developer Documentation. This documentation describes version 2 of OneUI. Both version 1 and 2 are included in the standard Domino 8.5.1 installation. This will be explained further down in this chapter (Using themes).

Website layout setup

The idea of the website layout setup is that the layout is centrally stored in the database and is reused for each individual page. This is achieved by using custom controls and editable areas (facets).

In order to determine the different design components to be used, we need identify the different layout components on the final web application. The below pictures shows the parts of the application layout (click on the image to see a bigger image).

1. Banner: the banner sits at the very top of the page and contains the application logo on the left and utility links (help, login) on the top right. Optionally, it can contain links to other applications that make part of the website.
2. Title bar: just below the banner, the title bar contains navigational tabs. Additional items, like a search function can be included on the right.
3. Left navigation: this will be our main navigation within the Document Library: just like a Notes client navigator, it will contain a list of links to the different views within the document library.
4. Content: this is the part that will contain the application's main content, like form and view contents
5. Footer: the footer can contain additional links like About this application contents, etc...

In order to centrally store the layout, we will create one custom control per layout component and then reuse these custom control in each of our XPages.

Reuse custom controls versus reuse XPages

There are two possible strategies for centrally managing the layout of a website. You could either create a set of custom controls and reuse them in each individual XPage (as proposed above), or you could create a single XPage with all layout in it, and then add a kind of "computed" custom control to display the variable content. Although a computed custom control does not exist in a literal sense (unlike computed subforms), there are ways to dynamically change the custom control in an XPage. For example, by using an editable area with a computed facet name. But even then, the first strategy remains far more prefrerable. Especially because using the second strategy (1 XPage, variable custom controls) would have as consequence that the same url is used for the entire application, since the url is defined by the XPage name. This would make linking individual pages impossible.

Create the layout

In this chapter, the different layout components/custom controls will be created. Once each component has been created, we will add proper styling and we will assemble all components together into one layout.
On each custom control, a panel container control will be placed. This will a serve as a container for its individual elements, and will give overall control for styling later on.

The banner

Create a new custom control, and call it "layout_banner".
Drag a panel container control into the custom control.
In the panel, drag a computed field control. This computed field will serve to display the user name in the top left corner.
Behind the computed field add a newline (ENTER) and drag a link control on the next line.
Do the same once again: newline + drag a link.

The two links will be used as "Help" and "Login/Logout" links in our application.



Don't worry about the missing top left logo in the banner: we'll add that later via css.

Save and close this custom control for now.

The title bar

Create a new custom control "layout_title". The title bar is the tabbed bar just below the banner.
Drag a panel container control into the custom control, and add two links into the panel. They will serve as tabs in our final application.



Save and close the custom control.

The left navigation

Repeat the above steps once again for a new custom control, called "layout_left". This time, you can add 4 links and give them label values:
All Documents
By Author
By Tag
By Status

As you notice, these links will be pointing to the different views within our application.

The footer

Same story here: create a custom control, "layout_footer" with two links, labelled "About the Document Library" and "Using the Document Library":

The content

In order to have a generic layout container for the page content, we will create a custom control with an editable area.

Create a custom control, "layout_content". Drag a panel container control in it, and in this panel, drag an editable area.



Save and close the layout_content custom control.

Bringing it all together

Now that we have defined each individual layout component, we will assemble our master layout into an XPage.

Open the XPage formDocument
Remove the existing custom control, ccFormDocument. The XPage is now empty.
From the controls palette, drag first the layout_banner custom control and then the layout_title custom control into the XPage.
Next, add a panel container control to the XPage: this will contain the left navigation and the content. Since these appear next to each other, this container will help is controlling their layout.
In the panel, drag the layout_left and layout_content custom controls. layout_content will appear under layout_left, but that's fine by now.
You'll notice that the editable area of layout_content now has a "target zone" with a green circle. This is the area where you can add variable content within the editable area.
Drag custom control ccFormDocument into this zone, and the green circle will be replaced by the contents of this custom control (=our library document form).

On the very bottom of the XPage, xnder the panel, drag layout_footer.

Save and preview the XPage. The result is far from fancy: just the same form as before with a bunch of links above and under it. This shouldn't be a big surprise: although we have build the foundations for our web site layout, no styling has been added so far. Time to get into the magic of themes!

Using themes

Introduced into Domino Designer 8.5, themes are powerful design elements that control overall layout of Domino web applications. With themes, you can give all your web applications a consistent look and feel, and include corporate branding.
Themes are much more than styles. They can include various style sheets and can also override/ specify individual control's look and feel. For example, in a theme you can specify a particular style class for all submit buttons in your application.
And last but not least: you can define multiple themes within an application, and then simple switch between themes via the application properties:




As described in the beginning of this chapter, we will apply IBM's OneUI look and feel to the Document Library sample application.

Built-in Domino themes

Domino 8.5.1 ships with three builtin themes: "webstandard", "notes" and "oneui". The source files (css and images) used these themes make part of the Notes client and Domino server installation. They can be found on the file system on the server and the client, in the notes data directory, under domino\java\xsp\theme: There's a folder for each of the themes, plus a folder "common" with shared images. The the "oneui" that is shipped with Domino is OneUI Version 1. In Domino 8.5.1, the theme OneUI V2 has been added for evaluation only and is not included as a standard theme. The source files are available in the data directory, under domino\html\oneuiv2: As you see in the above screenshot, the OneUI v2 theme comes in different "flavours": default, gold, green, metal and red. Each of the variations of the theme uses some common css files (folder "common") and images (folder "images"). The next tutorial step will demonstrate how to use either OneUI v1 or v2 into your application.

Creating a theme

Create a new theme resource, and call it "oneui".

You will notice that the new theme resource is opened on the Source tab of the editor, instead of the Design tab:



The source tab is the acual editing interface for themes, which are XML files.
A newly created theme will automatically contain a sample pattern to include stylesheets and one to define control properties. Also, a new theme inherits by default from "webstandard".

Replace "webstandard" by "oneui". This will automatically include the OneUI V1 theme definition.
Save and close the theme.

In the Application Properties design element, go to the XPages tab and replace the application theme "Server Default" by "oneui".
Save and close the Application properties and open the application in the browser.

You will notice that the XPages now have a blue-white gradient background: this is the background defined in the OneUI V1 theme.
Also, the Submit button in the formDocument XPage now has a style applied.

Apart from that, the page layout is still dull. This is because we still need to link the different layout components to the corresponding style classes in the theme.

Defining a OneUI v2 theme

We want to apply version 2 of the OneUI theme,as this is the theme that is documented in the IBM Lotus User Interface Developer Documentation.
OneUI V2 is not implemented in Domino 8.5.1 as a standard theme. In order to implement it, we need to include the source css files explicitly in a Theme design element.


Create a new theme, named "oneuiv2-core".
Leave extends="webstandard" unaltered.

Add the following code in the Source view of the theme editor:





Save and close the theme.

The above code includes the core OneUI v2 theme files into the theme design element. These css files are shared amongst the different flavors of the OneUI v2 theme.
Now, we will create the actual theme to use in the application:

Create a new theme, and call it "oneuiv2-default".
Replace "webstandards" by "oneuiv2-core" as the parent theme.

Include two css files into the theme:



Save and close the theme.

If you now apply the theme "oneuiv2-default" in the Application Properties and preview the application in the browser, you will notice that the little bit of fanciness which had been added with OneUI v1 has disappeared again. This is because of differences in the implementation between v1 and v2. Check the html source code in the browser, and you will notice that the theme css files áre included.

Referring to resource files of built-in Domino themes

You might have noticed something odd in the above explanation: the oneuiv2 theme files are in the directory <notesdata>\domino\html\oneuiv2, but the <href> resource properties point to a different location in the theme definition. Domino actually performs a mapping of the following locations: /.ibmxspres/global/theme/oneui/ maps to <domino data directory>\domino\java\xsp\theme\oneui /.ibmxspres/domino/ maps to <domino data directory>\domino\html\ /.ibmxspres/dojoroot/ maps to <domino data directory>\domino\js\dojo-1.3.2\ You can also use these mappings to refer to theme images withing your XPages: <xp:image url="/.ibmxspres/domino/oneuiv2/images/loading.gif" />

Adding style classes to the layout components

The key of applying OneUI v2 to an XPage application is assigning the right style class names to the right layout components.

OneUI v2 is all about classes. The Components section in the IBM Lotus User Interface Developer Documentation describes which classes to assign for each component. This is what were are going to do now: assign style classes to each of the layout components. We will also further finetune each component and give them the necessary containers (<div> tags) to make their look and feel correspond with the OneUI layout.

Assign a body class

Before diving into the individual layout components, we will add a style class to the body tag of our XPages:

Open the XPage formDocument and in the XPage properties view, go to the "Style" tab and assign the class "lotusui":



This class is a defined in OneUI v2 and controls overall page layout.
Do the same for the other XPage, viewAllDocuments.

Preview the XPages in the browser. They now have a blue background.

The banner

Open the layout_banner custom control and go to the Source view. The source code looks like this:



If we have a look at sample HTML in the OneUI specifications for a banner in the IBM Lotus User Interface Developer Documentation, we see this code:



In the sample HTML, there are three div containers, each with their own class: lotusBanner, lotusRightCorner, lotusInner.
We could now create two additional panel container controls in the custom control (there's already one), and assign the appropriate style classes to them:

This will work, but it will create unnecessary overhead. Instead of <xp:panel> tags, we could use simple <div> tags, as all we want to do with these containers is assign style classes to them.

Container tags in XPages

The XPages editing GUI only provides one simple container control for adding components: the panel. This translates to <xp:panel> in the source. A panel is useful when for example event handlers need to be added to the container control. In case the container only serves as a means to assign style classes, a simple <div> tag is sufficient. A third container tag, <xp:div>, is useful when for example a themeID needs to be assigned to the container. This will be demonstrated later on. The Designer GUI does not provide visual container controls for <xp:div> and <div>, but you can simply add them in the source code of the XPage or custom control.

Taking the above into account, we will apply the right styling to the banner by simply copying and pasting the sample HTML code into the source code of the custom control (instead of <xp:panel>), and by then replacing the hard coded user name in the sample by the computed field. The links "Help" and "Logout" can be copied from the sample and replaced later on.
Furthermore, we remove some unneeded features, like application links (will not be used within our application).

The resulting custom control looks like this:



As you notice, the three links in the banner have been placed in an unordered list. Unordered lists can currently not be added via Designer GUI controls: you need to add them via the Source view.

Save and close the custom control and preview the XPage formDocument in the browser.
The banner is displayed with a default logo and Help and Logout links:

OneUI v1 and v2 differences
A major difference in approach between OneUI v1 and v2 is that v2 uses style classes to apply css styling to components, while v1 uses the component ID (=the name of the component). If you want your application to be able to work with both themes, you can add the same style name as component name and as class name: <div id="lotusRightCorner" class="lotusRightCorner">

Computing the username

Open the layout_banner custom control again and select the computed field.
In the computed field properties, change the name to "cfUserName".
On the Value tab, select "JavaScript" as binding option and write the following script as value:



Save the custom control and preview formDocument.xsp to see the result.

The title bar

We'll perform a similar make-over to this custom control:
Review he titlebar sample code in the OneUI documentation and apply it to the custom control source code.

The result could be this:



The result in the browser:

The left navigation

Do the same for the layout_left custom control:

• add <div> container controls with the appropriate styles
• place the left navigation links in an unordered list

This is how the source code should look like:

The footer

For the footer, we will use a simplified version of the OneUI sample code, in which we drop the table headers and the unordered lists:

The content

There are still a couple of layout components that need styling: the actual form content, defined in ccFormDocument, and the panel in the XPage formDocument that contains both the left navigation and the custom control layout_content.

These components will be styled later, as we will first optimize our layout framework for reusability.

The custom control layout_content only acts as container for the actual content and doesn't need any style classes.

Optimize the layout framework

So far, the XPage formDocmument has been given a (partial) OneUI v2 look and feel by adding the layout components in the form of custom controls.
We could now add these custom controls to the XPage viewAllDocuments and to each consecutive XPage to be built within the Document Library application. This is a common approach.

Ideally, the entire website layout should be stored into one single custom control, which would make it easier to apply the layout framework to each individual XPage, and also to manage future layout framework changes.
This can be achieved by creating a "master layout custom control" which contains all indivdual layout custom controls (yes, they can be nested), and which contains an editable area for the content.

Create a main layout custom control

Create a new custom control, "layout_main".
Via the control palette, drag the custom controls layout_banner and layout_title into this one.
Under these controls, drag a panel container control and assign the style class "lotusMain" to it: this will be the container for the left navigation and the content. The style class will apply the appropriate OneUI styling.
In this panel, drag the custom control layout_left.
Under layout_left, but still within the panel, add an editable area, and name it "callbackContent" and give it facet name "facetContent".
Under the panel, add layout_footer.

The outline view of layout_main should now look like this:

In order to have the page content properly aligned, we need to place it within a container with the OneUI style class lotusContent:

Select the editable area facetContent, either via the Design view or via the Outline view.
Now open the Source view: the editable area is selected.
Write a div tag around this facet, with class "lotusContent":

As said before, you could also have added a panel container control via the Designer GUI instead of a <div> to achieve the same result, but as we only need a container for a style class, the div is preferable.

Save and close the custom control.

Adapt the XPages

Now we can update the the two existing XPages with this new layout framework:

Open the XPage formDocument and remove all custom controls.
Drag the custom control layout_main into the XPage.
Then drag the custom control ccFormDocument on the "drop zone" of the editable area layout_framework (=on the green circle).

That's it! The XPage is ready. Save and preview it.
The content container panel now has a white background, thanks to the lotusMain style class.

Repeat the same procedure for the XPage viewAllDocuments:
Remove the existing contents and drag layout_main into the XPage. Then drag ccViewAllDocs into the editable area of layout_main.


Now, you can apply the same trick to any other to be built XPage within the application: simply create a custom control for the contents and make an XPage, containing layout_main and the content custom control.

Add styling to the view All Documents

Add some additional styling to this view by adding the appropriate style classes:

Open ccViewAllDocs
Assign the style class "lotusui" to the custom control:

Add the styles "lotusActionBar lotusBtnContainer" to the actionBar panel and wrap the link in the actionbar in <span> tags with the attributes class="lotusBtn lotusBtnAction lotusLeft" role="button.
The action bar source code should look like this:




Select the view in the Outline view and assign the style "lotusTable" to it.
In the Source view, wrap the view (= <xp:viewPanel> into a <div> tag with a style attribute set to float left:

This is a tweak to make the view appear under the action bar in other browsers than Internet Explorer. There might be better ways to get this right.

Save the custom control. When previewing the view, you'll notice that the "New document" link has been transformed into a beautiful button.

Feel free to explore the style classes in the OneUI documentation and to further enhance the view.

Define a left navigation link

Just to make it more comfortable to work with our web application, we make the link "All Documents" work and make it open the XPage viewAllDocuments.

Open the custom control layout_left and select the first link, "All Documents".
In the Events view, add an action to the onClick event (=selected by default): server side (=default): select a basic action: open page: viewAllDocuments:

Under the server options, select "Do not validate or update data":

This option needs to be set, because clicking on the link "All Documents" should not perform any data validations. This will become more clear in the next chapter.
Save the custom control.

Since the layout is maintained centrally, the left navigation will now be updated in all XPages of the application.

Summary

In this chapter, we have given our very basic web application a OneUI look and feel. We have created a theme and a reusable layout framework, and we have applied the OneUI style classes to the various layout components.
In the next section, we will focus on the Library Document form functionality.