Developing a Web 2.0 client for IBM Lotus Domino

Create a Web 2.0-style, thin Web client for Lotus Domino using HTML and JavaScript. Building on the previous articles about the IBM Lotus Domino XML (DXL) framework, this article shows you how to extend your Notes/Domino applications with Ajax.

Raj Balasubramanian, Consulting IT Architect, IBM Mobile Foundation, IBM

Raj Balasubramanian is a Product Architect for IBM Software Group working on the IBM Mobile Foundation. He leads the client-services interaction for the IBM Worklight and IBM Mobile Foundation. Prior to his development role, he lead customer engagements delivering application and infrastructure related projects around SOA, BPM, Web 2.0 and Portal technologies. His interests range from anything technical to history, math and physics. He is currently pursuing his PhD at University of Texas at Austin. You can read about his past technical and personal escapades on his personal blog Gurukulam at

31 October 2006

Also available in Chinese Russian Japanese

In the article, "A custom DXL framework for accessing Notes/Domino data," we introduced you to the Lotus Domino XML (DXL) framework. From that article, you learned how to use the DXL framework to allow other applications to create, to view, and to update Notes documents. Then with the help of three LotusScript agents, you learned how to view a DXL document, how to create a document from DXL, and how to update a document from DXL.

In another article, "Building a JSR 168 portal application for Domino," you learned how to create a frontend to a Notes/Domino database using Java Specification Requests (JSR) 168 portlets.

Continuing our journey with the Lotus Domino DXL framework, this article looks at building a Web 2.0-style, thin Web client for the Lotus Notes/Domino Contacts database. We use a flat HTML file built with CSS/JavaScript constructs, hosted on a Domino server to access a Domino database using Ajax, but we also use some of the elements from the previous articles to create this Web 2.0 client.

This article assumes that you are an experienced Notes/Domino application developer with knowledge of JavaScript.

What is Web 2.0?

The term Web 2.0 was introduced by Tim O'Reilly at a conference in 2005. The term represents next-generation Web applications that are built using sound Web design principles and leveraging the simplicity of HTTP. Some common Web 2.0 applications include Google AdSense, Flickr, and blogs. Since then, the term has been generalized to form an umbrella of concepts and trends that characterize a style of Web applications. The core premise is that these Web applications use the Internet as their platform and expose functionality as services that are wired on demand by a user or by other applications (in other words, these applications consume the services) to provide a meaningful and rich application to the user. The technologies and concepts supporting a Web 2.0 style of application are:

  • Latest generation of Web browsers (Mozilla Firefox, Microsoft Internet Explorer 7, and so on)
  • AJAX
  • JavaScript
  • REST (REpresentational State Transfer, an architectural style on which the Web itself is based)

JavaScript: The language of choice

With Web 2.0-style applications gaining popularity, JavaScript has taken center stage. Because JavaScript is a flexible scripting language and because it is understood by nearly all Web browsers, it can be extended to include object-oriented constructs and can be used to build complex Web applications. We use JavaScript functions as objects, as methods, and as traditional procedural functions. You will see how to implement an MVC (Model View Controller) pattern in JavaScript over a flat HTML file.

About the application

The Web 2.0 client for Lotus Domino consists of a single HTML file and supporting scripts, images, and style sheet. The application is best viewed with Mozilla Firefox. For the purposes of this article, we use Firefox as our browser platform.

Figure 1 shows the application main page. This is the first screen the user sees after opening the Web 2.0 client in his browser.

Figure 1. Web 2.0 client for Lotus Domino
Web 2.0 client for Lotus Domino

You can click the Read Documents or Create Documents link. After you click Read Documents, you are taken to a screen similar to figure 2. In our sample, we show the name and the email address from the Contacts database (a database based on the Lotus Notes Personal Address Book template).

Figure 2. Read Documents view
Read Documents view

At this point, you can click Create Document or click one of the view entries to see more details. Let's click the first entry in the view. Figure 3 opens displaying key document fields in the Contacts database.

Figure 3. Contact information
Contact information

There is a mini-navigational view provided on the left with a listing of names. You can choose to click one of the entries in the mini-navigational view to see the details of that document, or you can edit the document that is displayed by clicking the Edit icon. You can then edit the document, and click the Save icon to save changes. You can always cancel your changes by clicking Close or clicking any other link.

If you want to create a document, click the Create Document icon from the menu. You are presented with an empty form to create a new document (see figure 4). You can then enter necessary details and click Save to create the new document.

Figure 4. Creating a contact document
Creating a contact document

Files in the application

The Web 2.0 client for Lotus Domino is made up of one HTML page and supporting JavaScript files for performing various actions executed by the user. The display is controlled by a cascading style sheet (CSS) and images. Figure 5 shows the relationships among the various files. The dxl.html file is a flat HTML file that uses style.css to format the presentation of content and uses the dojo.js, controller.js, and model.js to perform tasks.

Figure 5. File relationships
File relationships

All these files are in a single directory named web2.0 under the directory. Our hosting Domino server runs V7.0.1 on Microsoft Windows XP. The server supports basic Web authentication for the purposes of our application. If you want to enable session-based authentication, see the "Futures" section later in this article for necessary steps to get this application working.

In addition to this, we use the DXL agents from the article, "A custom DXL framework for accessing Notes/Domino data," and import them into the Contacts database.

Design principles

Because JavaScript lends itself to a procedural style of programming, you can use traditional methods of constructing the various functions needed to build your application. However, it is not very maintainable. Hence, you want to build the application as if you are building a three-tier Web application using your favorite Web application server (J2EE, Microsoft .NET, PHP, and so on). This implies that you need to maintain separation of concerns and to group like calls within a deployment unit. In essence, you can achieve these goals by applying Model View Controller design principles to your thin Web application.

You also want to adhere to the DRY (Don't repeat yourself) principle as much as possible. To accomplish that, you use the closures feature of JavaScript, which lets you treat a function as data to create classes and objects. You can then define classes and objects to be used in much the same way as we did in our JSR-168 portlet example (see the article, "Building a JSR 168 portal application for Domino").

Show me the design

Now, let's see how you can use MVC to build a simple Web application. Figure 6 shows the relevant objects, the methods they expose, and the deployment units to which they belong.

The view is handled by the main Web page (dxl.html); it also has helper functions and global variables for maintaining information. The primary view components are:

  • Menu class. Shows the menu items of Read/Create Documents.
  • mainView class. Handles display of the Domino view information in a tabular format.
  • miniView class. Handles display of the navigational view for quick access to documents, while in document display mode.
  • doc class. Handles display of the Domino document information and provides options to edit, create, and save.

The model is handled by the code in a model JavaScript file (model.js). The primary classes it defines are people (holds information from a Domino view) and person (holds information about the Domino contact document).

The controller is handled by the controller JavaScript file (controller.js) and contains several methods and attributes to perform its work. The primary method of this class is the action, which handles displaying appropriate information in the view based on the action performed by the user. The controller also accesses the appropriate Domino resource using Ajax calls and populates the appropriate model object and passes it to the view to display. The view in turn initializes an instance of the controller and delegates all actions and decisions.

NOTE: Ideally, you could separate the data access logic into its own deployment unit and keep the controller pure. However, we chose to combine it for simplicity's sake. You can refactor the code to isolate the data access functions into a separate file as homework.

Figure 6. The design
The design

The flow of some of the common activities are shown in figure 7.

Figure 7. Sequence diagram
Sequence diagram

Show me the code

Instead of looking at the entire application, let's take a look at salient points of the application and how we have implemented an MVC pattern.

Referencing external JS files in order

First, the dxl.html file loads the JavaScript files in the order of precedence:

<script type="text/javascript" src="controller.js"></script>
<script type="text/javascript" src="model.js"></script>
<script type="text/javascript" src="dojo.js"></script>

Establish key globals

Next, the application instantiates the controller object as a global. This is key to your design because every view action performed by the user is sent to this controller to handle. The application also sets up other globals for housekeeping purposes, such as watching for changed values in the fields. The code passes the string value of what the control is referenced as in this local Web page so that the controller object can reference that when it renders the view objects.

<script language="JAVASCRIPT">
var html_control = new control("html_control");

Encapsulate presentation components as JavaScript objects

Presentation components, implemented as JavaScript objects, are initialized by the controller object. The view/presentation objects take in a reference to the controller object name you created in the previous step ("html_control").

function mainView(ob,controller){

function miniView(ob,controller){
function doc(ob,controller){

The presentation components are instantiated by the control object located in controller.js.

function control(str){
 this.mainview = new mainView(this.ob,this);
 this.doc = new doc(this.ob,this);
 this.miniview = new miniView(this.ob,this);

Use the browser DOM to maintain context about the elements

Use <div> tags for all actionable items. You leverage available DOM attributes to carry context and pass it as part of the action performed by the user. In our example, we have defined document UNIDs as the name attribute value to carry context about the element.

<tr><td><a href="#" id="display_doc" name="'
+u.unids[x]+'" onclick="'+controller.varname+'

Send all actions from the view to the controller

Any link or actionable feature in your Web application is sent to the controller passing in a reference to itself.

<!--the view previous icon on the view page-->
<input type="image" src="prev.gif" id="view_prev" 
<!-- the link in the view to show the doc details-->

<a href="#" id="display_doc" name="'+u.unids[x]+'" 

Make all decisions based on the action and the context and centralize the logic in the controller

The core logic of what to do when actions are performed is encapsulated in the action JavaScript function as part of the control object. A switch/case statement is used to delegate to appropriate functions.

function control(str){
 this.action = function(u){
this.showMainView, this.mainview);
	// get doc details and redirect 
	// to appropriate display
	// get next set of view entries 
	// and show it in display

Define reusable objects for describing a Notes view and the Notes document

The model.js file contains two objects implemented as JavaScript functions: person for the document and people for the view. The presentation (dxl.html) handles only these domain objects. It's the responsibility of the controller (control function) to serialize the XML/DXL from the Domino server to the appropriate value object and vice versa.

function people(){

function person(){

Delegate the Ajax calls to a library/toolkit

Instead of implementing our own Ajax controls, we use the Dojo toolkit []. These calls are encapsulated in JavaScript functions that are attached as part of the control object.

this.serialize =function(url, fn, fn1){{url: url,
    load: function(type,data,evt){fn(data, fn1);},
    error: function(type,error){alert
    ("reached in error"+error.toSource());},
    mimetype: "text/xml"

Here you pass other JavaScript functions as parameters to the serialize method, which then sets it up to be called in case of a state change. In the previous code snippet, after the load is completed, the XML returned from the server is referenced in the data object, which is sent as a parameter to the function originally passed. This lends itself to reuse. You can use the same serialize method to show the content in the main view (which shows two columns of name and email) as well as the mini-navigational view used to access documents, when viewing document details.


As you will see in the next section, you need to ensure adequate permissions are assigned to the folder hosting this application on the Domino server. In addition, the operations (create, read, edit) are performed against the Domino database using the user's credentials. Hence, the group of users accessing this application should have appropriate privileges in the database ACL to perform the necessary functions. As with any other Web applications, it is best to end the browser session to be safe of any future exploits, if the user's machine is compromised.

Deploying to your server and testing

Use these tips to deploy the Web 2.0 client to your Lotus Domino 7 server:

  • Have a working Contacts database based on the Notes Personal Address Book template.
  • Ensure the ACLs are set up to allow the test user to create/edit documents and to read the view.
  • Install the LotusScript agents from the first article and ensure they are signed by an authorized Agent Signer.
  • Unzip the files found in this article to the directory. Ensure that the files are in a folder called web2.0 under the html directory.
  • Open the controller.js file and edit the variable called this.dominourl in the control function to the appropriate URL of your Domino server.

    NOTE: If you have session-based authentication turned on for Web logins, you should have the proper fully qualified hostname as part of the string. Also, ensure the appropriate ports are assigned if your Domino server is listening on a port other than 80.
  • Establish file protection for the newly created web2.0 directory. On the Basics tab of the File Protection document, accept the default options and modify the access control list to make sure that the domino/html/web2.0 directory is specified as the Path. On the Access Control tab, make sure that the "Current access control list" includes No Access for Anonymous and POST and Get for Default (see figure 8).
Figure 8. Access Control tab
Access Control tab

That's it. You can now test the application. Here are the steps:

  • Open Mozilla Firefox.
  • Access the URL: http://your dominourl/web2.0/dxl.html.
  • After you log in, you should be able to access the application.

Adapting to your own Domino application

Follow these directions to adapt the Web 2.0 client to any custom Domino database you may have:

  • Edit the models objects in model.js to reflect the domain your application represents. For example, let's assume the application is an ordering system. If you have a Domino view that shows orders and if documents are called order detail, then you may have a collection object called Orders and a document object called OrderDetails.
  • Edit the control code in controller.js to map the appropriate URLs, and edit the view column mapping you want displayed in the showMainView and showMiniView functions.
  • Finally, edit the mainView, miniView, and doc objects in dxl.html file to reflect the fields in the models objects from the first item.


You have seen how to leverage the DXL framework, which was introduced in the first article, to build a Web 2.0-style application to front a Domino database. You can make the presentation more sophisticated using the Dojo toolkit's UI utilities or any other DHTML means. You have also seen how to construct the Web application using design patterns for separation of concerns and better reuse. You can peruse the code in detail and adapt this application to a discussion database or other Domino application by editing the model.js, controller.js, and dxl.html files.


Sample scripts for this articleweb20.zip45 KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks

Zone=Lotus, Web development, XML
ArticleTitle=Developing a Web 2.0 client for IBM Lotus Domino