 | Level: Intermediate David DeJean, Partner, DeJean & Clemens
Vinod Seraphin, Senior Technical Staff Member and Architect, IBM Corporation
18 Jan 2005 Get started customizing Domino Web Access 6.5 for your organization's users and learn what changes you can make to the look and feel of the client with the skin editor tool and the server-side tags that let you change the user interface and layout.
From its beginnings, Domino Web Access (formerly iNotes Web Access) has been focused on providing a world class, high-performance, scalable Web experience. Domino Web Access has always included configuration settings to provide choices out of the box for things customers are likely to want to do, and we will continue to expand that configurability in the future.
But many customers want to modify Domino Web Access in ways that are beyond the scope of these simple configuration changes -- to add or remove menu items, for example, or to match the color scheme to their corporate colors. The Domino Web Access design team has devoted increasing attention to customization, and with Lotus Domino 6.5, the Domino Web Access template became even more customizable.
In this article, we'll concentrate on the options for customizing the Domino Web Access user interface and screen layouts. We will start with some background on how Domino Web Access pages are generated and the challenges of customizing them. We'll review some basic customizations to Domino Web Access 6.5. We'll discuss the special server-side tags used within Domino Web Access pages and the way that they're used in skins. We'll take a brief look at the Java-based skins editor tool, which you can download from the Sandbox. Finally, we'll take a look at what we're working on for Domino Web Access customization in Lotus Domino 7.
The challenges to customization
Unlike a typical binary executable program, such as the Notes client, the entire Domino Web Access user interface is composed of HTML, JavaScript, Cascading Style Sheets, and various graphic files. Domino Web Access pages are pieced together from these standard Web technologies using design elements that reside in a Notes database, Forms6.nsf, on the server. The contents of most Domino Web Access pages can be altered by editing their components. But there are some hurdles.
The first hurdle is that Domino Web Access is not a traditional Domino Web application. This affects customization efforts in a couple of ways. Knowing how to build Domino applications is helpful in modifying a Domino Web Access page, but the architecture of Domino Web Access doesn't follow that of a traditional Domino Web application. Domino developers will have a hard time identifying the correct design elements to modify. And the programming hooks aren't the same. In particular, there are frequent requests for something akin to QueryOpen and QuerySave – but these Notes form events aren't available in Domino Web Access.
Another hurdle is the JavaScript code used in Domino Web Access. It is obfuscated,or condensed, to improve the runtime performance of the application. The lower the byte count downloaded to the browser or loaded from the browser's cache, the better the application's performance, and the less bandwidth the application will consume. So Domino Web Access code is optimized for downloading in a process that's something like compiling. The Domino Web Access source code is maintained in text files. When a new version of the application is built, a special tool is run against the source to create the Forms file. This obfuscation tool removes all comments and replaces meaningful object names like those on the right in the example below with the much shorter (but much more cryptic) ones on the left. The process produces code that downloads much faster, but is much more difficult for a programmer to read. The complete translation table is available for download. A small sample of the 128 KB file looks like this:
BdA IERichTextArea_insertHTML
BdB CSequentialAsyncAction_doCommited
BdC CCSFormControler_getRepeatingDatesAreaHtml
BdD ShimmerException_getMessageFmt
BdE CCSFormControler_registerRescheduleDialog
BdF CResPickControler_disableFields
BdG FixupButtonWidths
BdH CCSFormControler_getCurrentWinDocCtx
BdI redirView
BdJ NSRichTextArea_getDataTextFormat
BdK IERichTextArea_adjustHeightToFitInWindow
BdL theWelcomeFrameset
BdM NPW_focusCaret
BdN isDirectoryInFileset
BdO CCSMeetingAction_grantPerform
BdP sCategorie
|
Starting with Lotus Domino 7, the Forms file will contain a File Resource design element named ObfuscationList which will store the appropriate mapping.
Skins present a different set of challenges to the developer. In Domino Web Access, the code that creates the elements of the user interface is organized as skins and skin components. Skin layouts have never been easily accessible. However, recently we developed a skin editing tool to help developers modify skins and to create new skin groups. For more, see "Working with Skins" later in this article.
In Lotus Domino 7, skins are now File Resource design elements and can easily be exported and modified using a traditional text editor and re-imported using Domino Designer.
The Domino Web Access template
The Domino Web Access template is different from other Domino templates. It fully inherits from the standard mail template (Mail6.ntf). This inheritance allows a mail user to access her mail file from a Notes client with all of the features of the standard template, and it enables that same mail file to be accessed from a browser using Domino Web Access as well. This diagram shows the relationship of the Domino Web Access template (iNotes6.ntf to the standard mail template) and the user's mail file (JUser.nsf in the diagram).
Figure 1. The standard mail template and user's mail file
The Domino Web Access template also makes special reference to a separate database, Forms6.nsf, that contains the Domino Web Access design elements. All the forms and subforms and most graphics used by Domino Web Access reside in this database located in the <domino data>\iNotes\ subdirectory on the server. (Some images used in the mail views are contained in the Domino icons directory or the mail template.) Forms6.nsf is a database (rather than a template) because Domino Web Access issues URLs directly to this database to retrieve many shared pages and elements. These are centralized in Forms6.nsf rather than distributed to individual mail databases for performance and disk space consumption reasons. All the Web browsers accessing mail files on a server use this common set of design elements that are also cached at the server to yield better performance.
When a user's mail file is set to use the iNotes6.ntf template, it inherits all the design elements in this template and also inherits the reference to the shared Forms file. These two sources, the template and the Forms file, provide the resources to build individual Domino Web Access pages.
The iNotes6.ntf template database includes some additional elements, such as agents that support bidirectional synchronization from the Notes client for the Personal Address Book and Personal Journal to the Domino Web Access Contacts and Notebook areas. There are also outlines and views used only by Domino Web Access to display calendar and journal entries and the TOC (Table of Contents or Top level menus).
Customization warning
While it is possible to customize Domino Web Access, and several customization projects are discussed in this article, they must be preceded by an important disclaimer:
IBM Lotus Support neither certifies nor supports Domino Web Access installations using altered templates or other customizations. IBM Lotus Support will instruct customers who open incidents resulting from a customized template to revert to the stock template to see whether or not the problem still occurs. If it does, IBM Lotus Support will troubleshoot the problem as it exists in the stock template. If the problem does not exist in the stock template, IBM Lotus Support will recommend that the customer remove the modifications and submit an enhancement request of the desired functionality for the next release. This policy includes the Forms6.nsf database as well.
You should plan any customizations accordingly and avoid customizing critical applications that you may later need IBM Lotus to support.
It is always good development practice to make back-ups of any database or design elements you intend to modify in a way that will allow you to reverse any changes to your installation of Lotus Domino. That said, there are some modifications that should not harm the functionality of Domino Web Access.
Pre-Lotus Domino 6.5 customizations
Versions of Domino Web Access before release 6.5 support only limited customization, mostly changes that can be made by editing the forms in the forms database using Domino Designer. Some modifications of the Welcome page and the view pages include:
- Change the logo
You can replace the logo in the upper left-hand corner of the screen with another image file. You must first create a form with a rich text field to the forms database to display the image. Then in the view named hResourcesbyName, edit the document named iwa.gif, and replace the logo image with your graphic.
- Modify entries in Table of Contents
You can reorder or remove entries in the top-level TOC (Welcome, Mail, Calendar, To Do List, Contacts, Notebook). If you don't want users to see the Welcome page, for example, it can be deleted from the TOC.
- Add views or folders to the outline in the Mail view
You can create new views or folders (non-categorized only) in the user's mail database and add them to the outline that appears to the left of the current view. You can reconfigure the default display order of this outline as well. You can modify existing view columns in Mail views, though not in the Calendar views.
Step-by-step instructions on how to perform these modifications are included in the IBM Redbook,
iNotes Web Access Deployment and Administration
.
Customizing Domino Web Access 6.5
Domino Web Access was enhanced in many ways with the release of Lotus Domino 6.5, and several of these changes were designed to make it easier for customers to make changes, especially to the graphical look of Domino Web Access. These changes make it possible to customize the Welcome page, to add items to the action bar and Tools menu, to customize the Domino Web Access Redirect login page, among others.
A good collection of examples of Domino Web Access customizations is included in the IBM Redbook,
Domino Web Access 6.5 on Linux
.
Several of the forms in the Forms6.nsf database can be modified by Domino developers using Domino Designer. For example, developers can modify the s_MailMemoEdit subform so that emails include the location or department. Developers can write code in the Scene_PreSubmit function (inside the Custom_JS_Extensions form) to validate the new field.
Domino Web Access 6.5 on Linux describes several customization projects that an administrator and Domino developer can perform:
- Modifying the action bar
The Redbook shows how to add new menu options to the action bar using two examples. One adds a function for showing a Web page -- in the case of the following example, the ITSO IBM Redbook Web page:
Figure 2. Action bar
The other menu customization creates a function to show an alert, dialog box, or both that displays the UNID of one or more selected documents. These action buttons are created by editing a form named Custom_JS in the Forms6.nsf file. Entries for the two buttons are added to the function named Scene_Actions. The first button needs no additional code. The second needs a new function, ShowDocUIDs, that displays an alert box with the UIDs of the selected documents.
- Adding a subfunction to the Tools menu
This customization adds an entry to the Tools menu that creates a new Help Request mail message with a pre-populated subject field:
Figure 3. Tools menu
Again, the Custom_JS form in the Forms6.nsf file is modified to add the entry to the Tools menu, and a new function, SendHelpRequest, handles the creation of the message.
- Customizing the Welcome page
You can customize the form named Custom_WelcomePage to add more choices to the Web site selection control from within the Edit dialog box of the Welcome page configuration. The following screen shows the Custom_WelcomePage opened for editing in Domino Designer:
Figure 4. Custom_WelcomePage form
The Redbooks Web page has been added to the list of pages with an entry in the titles variable (ITSO) and the URLs variable (http://www.redbooks.ibm.com/). When the form is saved and the HTTP server restarted, the ITSO entry appears in the list of available pages in the configuration screen. Setting Domino Web Access to open with the ITSO page displayed yields a result like this:
Figure 5. ITSO page in Domino Web Access
- Customizing the banner
By modifying the Custom_Banner subform, you can replace the Domino Web Access logo with another image or with a text string. The subform contains a single line of HTML code. To replace the logo with text, use the following line:
<div><h2><b>Custom text goes here</b></h2></div>
To replace the logo with a graphic, create an image resource, and enter the path to it in the subform:
<div><img src="../../../../inotes/forms6.nsf/alt-logo.gif?OpenImageResource"></div>
You can also change the appearance of the banner by customizing the image used for the banner background. This is more complicated. The background image is taken from an attachment to a document called gradblue10.jpg. You can find it in the Forms6.nsf database in the hRessourcesByName view.
No form to display the document exists in the Forms6.nsf database, so you must create it in Domino Designer. Give it the name Image and in it, create a field called Body and specify the rich text type.
When the form is saved, open the hResourcesByName view with the Notes client. Open the gradblue10.jpg document and detach the image file. Modify the image's colors with a graphics editing tool, and reattach the file without changing the name or the size of the image. Save and close the document. When you restart the HTTP server, Domino Web Access will display your new background.
In Lotus Domino 7, all images used by Domino Web Access are stored as files within File Resource design elements. This makes it much easier to extract the image, so it may be edited with any image editor and then re-inserted.
- Customize the Domino Web Access Redirect login and redirection screens
Domino Web Access Redirect, a new feature in Domino Web Access 6.5, enables a user to log into a server running the Domino Web Access Redirect database and be redirected automatically to a different server. This redirection allows users to access their mail files without needing to know the name of the file or mail server.
You can code additional functionality into the Domino Web Access Redirect. The Redbook suggests integration into a portal or modifying the login and redirection screens to match a company's color and design standards. Because these are regular Notes forms, rather than the Domino Web Access template, you can alter and enhance them in Domino Designer – but be careful not to change the fields on the login form, or the login process may not work properly.
You can also use the Notes.ini variable, iNotes_WA_LogoutRedirect, to specify a URL to redirect users to after logging out from Domino Web Access. You can use this variable to return users to the login page, a corporate portal page, or a customized exit page for Domino Web Access.
Working with skins
When Domino Web Access first came to market, it leveraged much of the HTML user interface development that had gone into Lotus Team Workplace (formerly QuickPlace). One of the key concepts of the QuickPlace UI is skins or themes that present a unified graphic look for a place. A number of skins are included with the product; and when you create a new Workplace, you can select the skin that will determine its appearance. Developers can tweak the cosmetics of a theme to change colors and fonts. They can customize the existing forms in the Workplace, and they can create additional ones that collect information in ways unique to the needs of the group.
(For more on customizing Lotus Team Workplace see the developerWorks: Lotus article, “Discovering Lotus Team Workplace customization,” and the IBM Redbook,
Customizing Quickplace
.”)
Following the Lotus Team Workplace model, all Domino Web Access forms and subforms use pass-thru HTML (even though this particular attribute isn't set). This pass-thru HTML contains special tags that are interpreted by the server as it puts together the response HTML: There is a tag to insert the skin, a tag to insert specific skin components or subforms, and other tags to do things such as evaluate computed blocks and to determine persistent and computed-only items.
All the main pages in Domino Web Access -- all the view pages, all the read or edit object pages, and the preferences page -- use a form named h_PageUI form in the iNotes6.nsf database. The form itself is very simple. It includes the HTML and body start and end tags. It also includes some special tags, including these:
- Computed text
The tag takes the form "@{ }". Within the braces, you can include any formula. In the Domino Web Access code, many of these formulas are compiled and the binary results are encoded in base64 before they are stored in the form or subform. Uncompiled formulas may also be placed between the tags. They are compiled and executed at runtime.
- InsertNotesSubForm (<InsertNotesSubform name=formname>)
The name may be any subform name. Domino Web Access uses a computed formula to determine the name of many of the inserted subforms: This is how it is able to use a single form to display all Domino Web Access pages.
- QuickPlaceSkin
The tag is just that: <QuickPlaceSkin>. This is the tag that inserts the entire contents of the relevant skin layout.
- QuickPlaceSkinComponent
This tag can take several arguments. In its simplest form, it consists of <QuickPlaceSkinComponent name=formname>. More complicated skin component tags emit JavaScript that contains the values of any specified attributes and then inserts a subform.
The following diagram includes examples of these tags and shows how they create a page:
Figure 6. QuickPlace tags
At the top of the form, the InsertNotesSubForm tag looks for a subform with the specified name and inserts the contents of the subform at the tag's location. In the example, this subform contains the <head> start and end tags and additional tags that bring in common external script files and a standard stylesheet.
Likewise, at the bottom of the form, the h_HTMLTailContent subform brings in some standard script that is invoked at the bottom of all our pages. We put some invisible HTML elements here, such as XML islands, and logic, such as polling for new messages and alarms.
In the middle of the form, the QuickPlaceSkin tag brings in the HTML that forms the body of the page. This includes a skin, and within the skin, other HTML packaged as skin components that are reused by the skins.
The skin component called PageContent contains the real meat of the page. Within this PageContent component, Domino Web Access follows the QuickPlace programming convention of “playing a scene.” A scene is simply two subforms related by special naming rules. The subform with the scene name is emitted into the content area of the HTML page, and a matching subform with the same scene name and a _Init suffix is emitted in the head area of the page.
The HTML below is a snippet of the code for a skin. It includes familiar tags that define the layout of the screen in a table, and two occurrences of the QuickPlaceSkinComponent tag. This tag calls in a subform with the name of the specified skin component and emits script that communicates with the skin component logic:
<table cellpadding="0" cellspacing="0" border="0" height="18">
<tr valign="middle">
<td class="s-bidi-flip" nowrap width="8">
<img width=8 height=21 class="s-stretch-y"
src="/iNotes/Forms6.nsf/h_ResourcesByName/tools-begin.gif/$FILE/tools-begin.gif?OpenElement&MaxExpires">
</td>
<td class="s-tool-text s-tool-bg" nowrap>
</td>
:
<QuickPlaceSkinComponent name=Logout>
<QuickPlaceSkinComponent name=ShimmerChat Format={
<td class="s-tool-text s-tool-bg-middle" nowrap><Item></td>}>
|
The skin editor
One of the difficulties of customizing Domino Web Access has been editing skins. There is a skin editor tool you can download from the Sandbox. The tool operates on the Forms6.nsf file and allows you to add, remove, or change the placement of objects on the view and form pages and to edit the stylesheet to change the colors and styles of objects. The tool looks like this:
Figure 7. Domino Web Access skin editor tool
The Browser Skins select box shows the available skin groups – a skin group is a set of skins that share the same stylesheet. The Domino Web Access Forms file includes three skin groups: h_ShimmerSkin (for Internet Explorer), h_ShimmerSkin_Gecko (for Mozilla), and h_ShimmerSkin_UB (for unsupported browsers). The only difference between the skin group used for Internet Explorer and Mozilla is the stylesheet.
The Domino Web Access Skins select box shows the skin types, such as h_Page, h_ListFolder, h_Edit, h_MailPage, h_Portal, and more.
The skin layout used for a page is determined by two computed-only variables, h_SetSkinGroup and h_SkinTypeOverride. h_SetSkinGroup specifies which skin group to utilize and h_SkinTypeOverride specifies which skin type to use. There are some defaults. If the document is being edited, the skin type defaults to the h_Edit skin. If h_Type==“1” (the QuickPlace identifier for a folder), the skin type is h_ListFolder. Otherwise, the skin type is h_Page.
To make a change to a Domino Web Access page, you have to edit the corresponding skin type in the skin editor. To determine which skin type to edit, view the page in a Web browser and display the source code. (For Internet Explorer, this is done by invoking the View/Source menu item or right-clicking the displayed page and selecting View source.) Two JavaScript var definitions on the page will identify the current skin group and type: h_CurrentSkinName and h_CurrentSkinType.
var h_CurrentSkinName = 'h_ShimmerSkin';
var h_CurrentSkinType = 'h_ListFolder';
Coming in Lotus Domino 7
A great deal of work is being done on Domino Web Access to make it even more customizable in the next version of Lotus Domino. Some of these changes have already been mentioned earlier in this article. Major enhancements include:
- Formulas, as noted, will be available in their original text within forms and subforms. The server-side forms/subforms cache has been enhanced to compile formulas the first time the form or subform is accessed, and then to store the compiled result within the cache. In this manner, customizability is not sacrificed for performance.
- All the images in Domino Web Access will be stored as File Resource design elements, so they may be more easily identified and replaced.
- A new File Resource design element called ObfuscationList.txt will contain the mapping of legible code names to the short cryptic names.
- Skins will be easier to edit. The skins editor tool mentioned earlier in the article won't be needed for Forms7.nsf (the Domino 7 Forms file). All skins will be stored as File Resource design elements. The names of relevant design elements will be the skin group name followed by a hyphen followed by the skin type name.
- Domino Web Access 7 will support QueryOpen and QuerySave agents.
- A special form named Domino Web Access_tags will store definitions for custom tags with a Domino Web Access namespace. You'll see these tags in the pass-thru HTML within the forms and subforms of the Forms7.nsf file. For example:
<DWA:getvars includeall="0" />
This form will provide a way to avoid (or at least reduce) the volume of computed Notes formulas that occur within pass-thru HTML and provide another performance enhancement.
Obviously, Lotus Domino 7 will mark a major improvement in the customizability of Domino Web Access. A future developerWorks: Lotus article will explore in more detail how Domino Web Access decides which “scene” to play when manipulating a specific document in the mail file with a particular Form type, how it displays the actual field values for a particular Form type, how additional fields might be added to a specific Form type by customizing the Notes Dictionary entries, and how to utilize the new QueryOpen and QuerySave agent functionality.
Resources
About the authors | | | David DeJean has been working with and writing about Lotus Notes and Domino for as long as they've existed. He was co-author of the very first book about Notes, "Lotus Notes at Work," and has been an editor and writer for a variety of computer publications. He is a Lotus CLP and a partner in DeJean & Clemens, a firm that does Notes and Internet application development and technical and marketing communications. |
| | | Vinod Seraphin is a Senior Technical Staff Member and lead architect for Domino Web Access and the Domino Common PIM Portlets. Domino Web Access (formerly iNotes) was "born" from Vinod's prototyping efforts to develop a very compelling Personal Information Manager (PIM) within a browser. He has been with Lotus/Iris/IBM for over 10 years. Prior to Domino Web Access, Vinod was the Software Architect for Lotus Organizer. He has an MS in Computer Information Systems from Boston University and a BS in Computer Science and Engineering from MIT. He also is an avid professional sports fan and enjoys softball, bowling, traveling, and spending quality time with his family. |
Rate this page
| |
