The enhancements to IBM Lotus Team Workplace (formerly QuickPlace) have turned what was once a limited collaboration tool into a very rich, customizable environment for collaboration and knowledge sharing. This article discusses the customization options for Lotus Team Workplace with particular focus on the Explorer PlaceType, which you can download from the Sandbox. It also refers to the IBM Lotus Redbook Customizing QuickPlace. (For URLs, see the Resources section at the end of this article.)

QuickPlace was developed to provide small workgroups and teams a Web-based collaboration tool that would allow users to easily create standard shared spaces that contain the tools they need to work on projects -- rooms, folders, documents. The tools allowed groups to conduct threaded discussions, to share documents, and to create slideshows and archives. Each group's space can operate with security that is as granular as the sensitivity of the material and the size that the team requires.

The original design point for QuickPlace was small groups and short-term projects: Places could be created with minimal infrastructure and IT support, and just as easily be deleted when the project was finished. But in the five years since the product's introduction, Lotus Team Workplace has been adopted by users who see their Places as long-term solutions for collecting and providing access to knowledge across large enterprises. In-house developers and third-party consultants have used Lotus Team Workplace as a platform for developing solutions to business problems in a wide variety of industries.

Lotus Team Workplace has kept pace, and enhancements have made Workplaces much more customizable. Many of these changes are available to users. Users who create new Workplaces can, for example, use the Customization controls within Lotus Team Workplace to choose different themes or "skins" for their Workplaces from a number shipped with the program. They can further tweak the cosmetics of the theme they have chosen, changing colors and fonts. They can customize the existing forms in the Workplace or create additional ones that collect information in ways unique to the needs of the group. They can also create simple workflows.

Developers can take the customization even further. As a developer, you can create PlaceBots that are analogous to Domino agents as components of the Workplace that change the way documents are handled or the way the Workplace is presented to users. You can create entirely new themes to bring together just those components required to make a Workplace a targeted solution to a particular problem. When you have created new themes and PlaceBots, you can make these reusable by turning them into PlaceTypes, which are to Lotus Team Workplace what application templates are to Domino. You can also connect Workplaces to other applications and data repositories by using the Lotus Team Workplace event interface, using the QuickPlace Java API, or writing C or C++ code using the QuickPlace Developer's Kit and the Lotus C API Toolkit.

The Explorer PlaceType

A standard Workplace created in Lotus Team Workplace consists of rooms, folders, and documents. The user interface provides a table of contents for the Workplace, which appears in the user interface as blue and white navigation bars (on the left in this screen):

The Workplace owner creates a list of members who can access the Workplace, who can see its contents, and who can create new documents. All the members of the Workplace have access to all of its contents, so if more granular security is needed the Workplace owner can create rooms within the Workplace. Each room has its own membership, which is a subset of the membership of the Workplace. Team leaders can thus conduct a discussion that can't be seen by other members of the team, for example.

Each room has its own table of contents (TOC), which is slightly different from the Workplace's TOC:

As Workplaces have grown and become more complex over time, one limitation of the standard user interface has become obvious: As you navigate into inner rooms, you lose context. You see only the TOC for that room. You can nest rooms within rooms, but the standard TOC doesn't reflect this nesting or provide the user with any information on his location within the Workplace.

The Explorer PlaceType provides the user of a complex Workplace with a wide-angle view of the Workplace's structure, and more direct navigation across that structure. Instead of the standard TOC, Workplaces created with the Explorer PlaceType display a panel that resembles the Windows Explorer. Dotted lines indicate a hierarchical structure, and small icons indicate the type of object within the hierarchy:

The Explorer PlaceType was created by Xavier Defossez with IBM Lotus Consulting in France. Tony Estrada, a five-year veteran of the Lotus Team Workplace development team, refined it further and used it as the basis for a presentation with Helen Dai on customizing Lotus Team Workplace at Lotusphere 2004.

The enhanced navigation is just one of the features of the Explorer PlaceType. It includes a custom theme that removes several items from the TOC and makes them action buttons above the workspace instead: Advanced Search, What's New, Help, and Work Offline. A Windows Explorer-style address bar is also added to display the path through the Workplace to the user's current location:

This page obviously puts a different theme or skin, a different look and feel, on the Workplace while leaving the underlying functionality unaltered. This relationship between appearance and function is created in the theme document. A theme is a set of HTML (or DHTML) files and associated stylesheets and graphics. It uses standard HTML constructs to accomplish several purposes:

• To create page layouts for several types of pages -- a page being read, a page being edited, a Headlines folder, and more.
• To specify styles for display elements by invoking the Lotus Team Workplace Graphics Server.
• To place Lotus Team Workplace UI components, such as the search bar, page title, action buttons, and many more, on the page. It does this by using special <QuickPlaceSkinComponent> tags embedded in the HTML code.
• To call PlaceBots that perform other actions associated with the page. These actions may be invisible to the user, such as logging the creation of a new document and recording the name of its creator. Or, like the action that creates the Explorer TOC panel, they may be very visible.

If you've ever written any HTML, you know what the first of these is all about -- using HTML to create and position the elements of the page. The last three of these, however -- the Graphics Server, the Components tags, and PlaceBots -- are not standard HTML. Let's take a closer look.

The code for a theme

In order to see all the code for the Explorer PlaceType, you should download the zipped file from the Sandbox and create a Workplace with it. Open the Workplace and save the custom theme page.htm to a file on your hard disk.

Using the Graphics Server

Page.htm calls the Lotus Team Workplace Graphics Server by using standard <IMG> tags, but uses them in a very non-standard way. Here is the code in the Explorer theme document that creates and styles the page heading "Lotusphere 2004" you see in the example screen above:

<td background="Page_Files\fond_barre.gif" height="32" >
<center>
<img src="../../../QuickPlace/xplorer01/$resources.nsf?GetImage&
TextString=%20LotuSphere%202004&OutTransColor=e5e599&
FontName=Encino&FontPointSize=16&FontColor=ff6600&
FontBold=1&FontAntiAliasColor=e5e599&EffectType=Shadow&
BlurFactor=3&ShadowColor=808080&ShadowXOffset=2&
ShadowYOffset=2&BkColor=e5e599&Animation=FADEIN&
AnFrames=16&AnDelay=15&AnLoop=0&FontGroup=h_FontModern" 
border="0">
</center>
</td>

Typically an HTML image tag specifies the location of a static file. This tag, however, requests an image file from the Lotus Team Workplace Graphics Server and passes in all the parameters the server needs to create the graphic. In this case, it calls the words Lotusphere 2004 in the Encino typeface, colored orange with a gray drop shadow.

The Graphics Server works on the fly and makes it easy to tweak Lotus Team Workplace themes, changing text, colors, and visual effects. The Graphics Server is what makes it possible for users to change so much of the look and feel of a Workplace so simply.

Calling Components

Component tags also look something like HTML, but go way beyond it. This code in page.htm places the Advanced Search component, a standard function of Lotus Team Workplace, on the page:

<QuickPlaceSkinComponent 
	name=AdvancedSearch
	prefixHTML={}
Format={<td onMouseOver=(this.background=fond_action.src) 
onMouseOut=(this.background=pix_transparent.src)><
img src="Page_Files\rechercher.gif" height="17" width="27" border="0" 
align='top' valign='top'><item>&nbsp;&nbsp;</td>
	
	}
		
EmptyFormat={}
	replaceString={}>

Note that several of the tag attributes are left empty. The Format attribute includes JavaScript code to create a rollover button.

Just as the Graphics Server works on the fly, the Lotus Team Workplace server rewrites this code (which a browser would ignore) on the fly into JavaScript that specifies a URL to call the Search function that can be understood by the browser.

Running PlaceBots

Finally, here's the code in page.htm that runs the PlaceBot to create the hierarchical TOC:

<iframe 
	src="../../../main.nsf/menu?openagent" 
	visibility="show" 
	FRAMEBORDER="0" 
	SCROLLING="auto" 
	width="180" 
	height="380" 
	ALLOWTRANSPARENCY="true">
</iframe>

This is the simplest of the three examples, but it has the biggest impact on the finished product. Obviously these nine lines of code are just a wrapper for a lot of work that gets done on the Lotus Team Workplace server.

The iframe tags create a floating frame to contain the TOC document on the page. The document itself is indicated by the SRC attribute, and in this case, it is not a static file, but dynamically generated by the PlaceBot named menu in the Workplace's main.nsf database.

Back to top

Inside the menu PlaceBot

The PlaceBot named menu scans all the documents in the Place and creates a JavaScript file that, when passed to the browser, uses the document.write method to display the TOC. That sounds simple enough. It even looks simple: The code for the menu is broken into four subroutines and a function that you can see by opening main.nsf in Domino Designer. (Look for menu under Shared Code - Agents). But what it does is complex.

First, the LotusScript builds JavaScript . . .

The PlaceBot generates the JavaScript that generates the TOC. Or another way to look at it: If the menu PlaceBot were a manufacturing robot in an auto factory, it wouldn't build a car. It would build a robot that would build a car.

The PlaceBot begins by declaring three variables:

• Path, the path to the database, as a string
• TextToPrint, the string that will eventually become the JavaScript contents of the iframe
• menuLevel, an integer representing the level of the current document in the hierarchy

Then the subroutines are executed in turn -- Printscript, getPath, MenuRoom, and PrintEnd -- and finally a Print statement sends the TextToPrint string to the browser.

Printscript

The Printscript subroutine starts off the TextToPrint string by writing to it a very long text string composed of a stylesheet and all the JavaScript functions used to create the TOC.

getPath

This brief subroutine returns the properly formatted path to the database. It's only seven lines of code, but making it a subroutine is a minor performance booster. The path is calculated only once, rather than for each document.

MenuRoom("main.nsf")

This is where the heavy lifting is done. MenuRoom examines every document in the Workplace and captures several items of information about it:

• Level in the hierarchy
• Type
• Title, if it has one
• The name of the icon that identifies its type (which it gets as a returned value from the function GetImageType)
• A URL link to the document relative to the currently open document

It writes this information to the TextToPrint string as a call to a JavaScript function named setEntry. The LotusScript code looks like this:

And the resulting line in the output might look like this:

When the browser executes these calls, they load their data into a set of arrays.

PrintEnd

After all the documents have been added, the PrintEnd subroutine tags on the JavaScript code that invokes the processing of the arrays of menu item data and the </script> tag.

The last line in the agent's Initialize object, Print TextToPrint, ships the JavaScript to the iframe, where the browser's JavaScript interpreter takes over.

. . . Then the JavaScript builds HTML

The JavaScript interpreter unpacks both its tools and its raw materials from the package created by the PlaceBot.

It starts with a local style sheet for the TOC that sets headline type sizes and mouseover fonts and colors. Then it creates the arrays and populates them with the data from main.nsf using the setEntry function:

function setEntry( Alevel,Atype,Atexte,Aimage,Alien)
{
  level[nb] = Alevel;
  type[nb]  = Atype;
  pere[nb]  = Apere;
  status[nb]= 0;
  textString[nb] = Atexte;
  image[nb] = Aimage;
  line[nb]  = Alien;
  nb+=1;
}

(The French origins of the code are detectable in the variable names. Remember that you can see all the JavaScript in the menu PlaceBot's subroutine named PrintScript.)

A JavaScript function named processMenuItem mirrors the function of the PlaceBot subroutine named MenuRoom, constructing another long text string. This one, however, is called chain rather than TextToPrint and it's not JavaScript, but HTML. This HTML is sent to the browser with the command:

(It's a little more complicated for Netscape browsers because Netscape doesn't support the innerHTML property; but as you can see if you look at the JavaScript, it's still only a couple of lines of code.)

Ideas for enhancements

While the Explorer TOC shows only the current room expanded to display its contents, the menu PlaceBot reads the entire contents of all the rooms in the Workplace each time the user enters a new room. This has performance implications for large Workplaces with many rooms and inner rooms, and it would be good to limit the scan to the menu of rooms plus the contents of just the current room. Another very desirable enhancement would be to enable room managers to add documents from folders to the TOC for the room as a way of calling users' attention to them.

Back to top

Conclusion

The Explorer PlaceType's hierarchical TOC is a valuable addition to IBM Lotus Team Workplace that helps make complex Workplaces easier to navigate and use. And for Domino developers, it is also a valuable case study in customizing Lotus Team Workplace -- and a starting point for creating your own new themes and PlaceBots.

Resources

• Download the Explorer PlaceType for the Sandbox.
  
  
• For a much deeper dive into customizing Lotus Team Workplace, see the IBM Lotus Redbook Customizing QuickPlace.
  
  
• Download the code examples discussed in Customizing QuickPlace via FTP. (The examples are contained in four zipped files: 6000-all.zip, 6000repo.zip, 6000ddoc.zip and 6000tkey.zip.)
  
  
• For the QuickPlace Developer's Kit, as well as a variety of downloadable utilities and example PlaceTypes, see the developerWorks: Lotus site for Team Workplace Programming the Lotus Team Workplace event interface also requires the Lotus C API toolkit. You can download the Domino 6.5 versions for various platforms.
  
  
• Other LDD Today articles related to customizing Team Workplace include:
  • "Creating QuickPlace Custom Forms"
  • "Extending QuickPlace Workflow"
  • "Adding Calendar Roll-Up to QuickPlace"
  
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The Explorer PlaceType
• Inside the menu PlaceBot
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers