Extending the IBM Lotus Notes V8 sidebar and toolbar

The new architecture of IBM Lotus Notes V8 enables a wide range of new ways to extend and customize the user experience. This article looks at two locations in this environment, the sidebar and toolbar, and discusses how to add functionality by using Eclipse plug-ins.

Brian Leonard, Lotus Notes Client Developer, IBM

Brian Leonard is a Lotus Notes client developer. In IBM Lotus Notes V8, he worked on search, email rendering, delayed image loading, spell check, and extensibility. He'd like to be taller but can never find the right extension point.



10 April 2007

Also available in Chinese Japanese

IBM Lotus Notes V8 is a whole new world in many ways. The update of the user experience is probably the most noticeable update. Out of the box, Lotus Notes V8 should make the user feel much more at home. If you are an application developer or administrator interested in helping users increase productivity, you can work with one of the more subtle changes in Lotus Notes: the ability to customize user experience in ways never before possible.

These changes are made possible because of the new architecture of Lotus Notes. Specifically, Lotus Notes is now built on top of and benefits from some platforms that were designed to be extended. At the core of this is the open source Eclipse platform. Eclipse provides the glue that allows many components to work together seamlessly, yet be separate enough to allow easy customization.

IBM Lotus Expeditor V6.1 is a new platform that can be used to deliver your applications to users’ desktops conveniently and easily. Lotus Expeditor adds a variety of features to the Eclipse technology that it extends; these features include intelligent provisioning and configurable user interface. Additionally, Lotus Expeditor is the base for IBM Lotus Sametime V7.5 and the upcoming Lotus Notes V8 clients as figure 1 shows.

Figure 1. IBM Lotus client architecture
IBM Lotus client architecture

This structure allows you to target development at the Lotus Expeditor platform that can be used in IBM Lotus Notes V8. Going forward, these components can be reused without modification in Lotus Sametime and the Lotus Expeditor stand-alone product. Additionally, it allows businesses to create applications and tools once that can easily be provisioned in a variety of environments.

This article looks at two user interface components added to the Lotus Notes client, SideNote and QuickNote. Both applications enable the user to write notes in either the sidebar or the toolbar of the client. This article explains how you can contribute your own components through Eclipse plug-ins to these locations.

Setup

First, you need to install the Lotus Notes V8 software.

Then you need to set up Eclipse, which you can download at no charge. You then need to set up Eclipse to work with the Lotus Notes environment. The following steps assume you installed Notes to the default location of C:\Program Files\IBM\Lotus\Notes and have a data directory of C:\Program Files\IBM\Lotus\Notes\Data. If your environment is slightly different, use your location in each place.

Start the Eclipse IDE, and set the target platform by doing the following:

  1. Choose Window - Preferences.
  2. Expand Plug-in Development.
  3. Select Target Platform.
  4. In the Location edit control, type or browse to C:\Program Files\IBM\Lotus\notes\framework\eclipse.
  5. Click the Reload button, and then click OK.

Next, you create an additional installed JRE:

  1. Choose Window - Preferences.
  2. Expand Java.
  3. Select Installed JREs.
  4. Click Add.
  5. For JRE name, enter Notes JRE.
  6. Enter or browse to C:\Program Files\IBM\Lotus\notes\framework\rcp\eclipse\plugins\com.ibm.rcp.j2se.win32.<version number> for the JRE Home Directory.
    For Lotus Notes Beta 3, this value is: com.ibm.rcp.j2se.win32.x86_1.5.0.SR4-200705170110
    (NOTE: This populates JAR files to the lower part of the pop-up box.)

Next, you create a new runtime configuration by following these steps:

  1. Choose Run - Run, and then select Eclipse Application.
  2. Right-click and choose New.
  3. Enter a name (for example, Notes).
  4. Under Program to Run, select Run a product, and then select com.ibm.notes.branding.notes.
  5. In the Runtime JRE, select Notes JRE.
  6. In the Arguments tab, enter the following in the Program arguments text box:
    -personality com.ibm.rcp.platform.personality
    -product com.ibm.notes.branding.notes
    -debug
    -console

Enter these arguments in the VM arguments text box:
-Drcp.home=${notes.install}\framework
-Drcp.data=${notes.data}\workspace
-Drcp.install.config=user
-Dosgi.install.area=${notes.install}\framework\eclipse
-Dcom.ibm.pvc.osgiagent.core.logfileloc=${notes.install}\framework\rcp
-Dcom.ibm.pvc.webcontainer.port=0
-Declipse.pluginCustomization=${notes.install}\framework\rcp\plugin_customization.ini
-Declipse.registry.nulltoken=true
-Djava.protocol.handler.pkgs=com.ibm.net.ssl.www.protocol
-Djava.util.logging.config.class=com.ibm.rcp.core.internal.logger.boot.LoggerConfig
-Dosgi.hook.configurators.exclude=org.eclipse.core.runtime.internal.adaptor.EclipseLogHook
-Dosgi.framework.extensions=com.ibm.rcp.core.logger.frameworkhook
-Xbootclasspath/a:${notes.install}\framework\rcp\eclipse\plugins\${rcp.base}\rcpbootcp.jar;

Next, follow these steps to complete the runtime configuration:

  1. Click Variables.
  2. Click Edit Variables.
  3. Click New.
  4. Enter notes.install for the name.
  5. Enter the path where you installed Notes for the value, and then click OK. This path should not have any spaces in it. For example, if you installed to C:\Program Files\Lotus\Notes, your notes.install value should be:
    C:\PROGRA~1\IBM\Lotus\Notes.
  6. Repeat steps 1 to 3.
  7. Enter notes.data for the name.
  8. Enter the location of your data directory for the value, and then click OK. For example, use the default:
    C:\PROGRA~1\IBM\Lotus\Notes\Data.
  9. Repeat steps 1 to 3.
  10. Enter rcp.base for the name.
  11. Enter the version of the folder name for com.ibm.rcp.base plug-in that is installed for the value, and then click OK. To do so, go to the following location: <notes install location>\framework\rcp\eclipse\plugins. There is a folder that looks like com.ibm.rcp.base_6.1.1.<date>.
    For example, in Lotus Notes Beta 3, this value will be:
    com.ibm.rcp.base_6.1.1.200705170110
  12. Click OK, and then click Cancel to the Select Variable dialog box (if you click OK to select variable, it adds the variable at the insertion point).

To enable Notes security from the IDE, you need to uncomment two lines. In <notes install location>\framework\shared\eclipse\plugins\com.ibm.notes.branding_3.0.0.<version number>\notes_plugin_customization.ini, uncomment the following two lines by removing the leading # character:

com.ibm.rcp.security.auth/loginEnabled=true
com.ibm.rcp.security.auth/loginConfigName=NOTES

Now, select Run/Debug to launch Lotus Notes.

Finally, download the code provided with this article and unzip it to a new folder. To import it into Eclipse, you need to import the existing projects.

  1. Choose File - Import.
  2. Select General - Existing Projects into Workplace, and then click Next.
  3. Browse and select the folder that you unzipped the code to and click OK.
  4. Click Finish to complete the import process.

Extending IBM Lotus Notes

Lotus Notes is built on top of the Eclipse Rich Client Platform (RCP) and IBM Lotus Expeditor. You extend Lotus Expeditor by creating Eclipse plug-ins and deploying them using the provisioning included in Lotus Expeditor.

A plug-in is a component that provides a piece of functionality. Any given plug-in can define other plug-ins upon which it depends, thus permitting granular componentization and code reuse. A plug-in can also contribute functionality to the plug-ins upon which it depends through extension points.

The concept of extension points is the key to understanding how Eclipse works. An extension point allows a component to define a contract for other plug-ins to contribute functionality. The contributing plug-in fulfills this contract by defining specific values through XML. These values can be key data in the form of strings or the names of Java class files that implement key interfaces. For example, the Eclipse platform defines an extension point to add a menu item to any menu. The contributing plug-in provides the ID of the top-level menu, the name shown to the user, and the name of the Java class that defines the action to execute when the user clicks the item. For more information about extension points and the Eclipse framework, check out the Eclipse Web site.

To extend Lotus Notes, you use the same mechanism. In the following sections, we describe the extension points used to contribute to the sidebar and the toolbar. These are just two of the many available extensible components using this approach, but they illustrate the concept and provide a template for contributing to two of the more interesting client locations in Lotus Notes.


Application use cases

As you work, you most likely need to store little pieces of text temporarily. There are many approaches you can take to address this need. For instance, you can create text files on your desktop and paste in the information you want to store. You also may forget to delete these files and inadvertently create a cluttered environment of randomly named text files.

The applications discussed next take two different approaches to solving this problem.

SideNote lives in the sidebar and consists entirely of a large text area. It allows you to paste or type text that is preserved until you delete it. This data also remains across client sessions so that it is always available. SideNote is ideal for those times when you need to paste several pieces of information someplace for quick reference soon.

QuickNote performs a similar function from the toolbar. Clicking the QuickNote button displays a small text window in which you can type text. This text can be saved to a folder on the hard drive. Later, you can reload this and other text documents in that folder into the window. QuickNote works as a scrapbook for more permanent text or information that you need to access often and quickly.


SideNote sidebar application

The Lotus Notes sidebar presents an exciting opportunity for application contribution. It provides significant screen real estate and consistent availability as shown in figure 2.

Figure 2. SideNote application
SideNote application

You can expand, minimize, and float sidebar applications. You can also use several sidebars at one time. For instance, IBM Lotus Notes V8 comes with sidebar components for Lotus Sametime contacts, the current day’s schedule, a feed reader application, and a view of your activities. By fulfilling the extension point contract, you can add your own components to this location.

SideNote has fulfilled this contract to add a text box to the sidebar. The application is also notified when the user closes it. SideNote takes this opportunity to save the text to a file on the hard drive. When you create SideNote again, it pulls this text back up for you.

Finally, through a separate set of extension points, Eclipse developers can add menu options to any sidebar application. SideNote includes two menu options, Save as file and Load from file as shown in figure 3.

Figure 3. SideNote menu options
SideNote menu options

Sidebar extension points

Let’s look at how to add SideNote to the Lotus Notes sidebar. If you take a look at the com.ibm.lotuslabs.ui.sidenote plug-in in the Eclipse integrated development environment (IDE), you see its key components. These include:

  • Plugin.xml, which defines the extension points to which it contributes
  • MANIFEST.MF, which defines dependencies
  • Java source files, which implement applications and actions

The first thing to understand is the concept of an IViewPart, which is an interface defined by Eclipse roughly equivalent to a rectangle on the screen. In the Eclipse world, IViewParts make up a majority of what you see. For instance, the outlined areas in figure 4 are all IViewParts.

Figure 4. IViewParts in the Eclipse client
IViewParts in the Eclipse client

In Lotus Notes, these same pieces are used. Even though we've called SideNote an application in the sidebar, it really is an IViewPart. Specifically, we created SideNoteViewPart as shown in figure 5.

Figure 5. SideNote plug-in code
SideNote plug-in code

This Java class knows how to build the application. The contract is defined so that the createPartControl method is called when the part is created. In this case, you fill the available area with a single text control. You pass in flags to create scroll bars and to tell the text to wrap. Many visual components in Eclipse are created using a technology called Standard Widget Toolkit (SWT). It is SWT that makes it so easy and makes it work across platforms. You can also listen for special key combinations. For instance, when the user presses Ctrl + A, you can select all the text. Finally, you tell it to save its state when it is disposed. In Eclipse, dispose is called when a visual element should be removed or closed.

After you create an application, you need to tell the platform about it. You do this through the org.eclipse.ui.views extension point in the plugin.xml as shown in figure 6.

Figure 6. SideNote view extension point
SideNote view extension point

You give the view an ID; you may want to use the Class name because it is typically unique.

Now that you have declared the functionality, you can place it in the user experience using another extension point. This separation of functional units and UI placement is a common theme in Eclipse. The Lotus Expeditor platform defines the extension point to place a view in the sidebar. You contribute to the com.ibm.rcp.ui.shelfViews extension point and point it at the SideNote view as shown in figure 7. The following fields and values are included in the shelfViews extension point:

  • id: com.ibm.lotuslabs.sidenote.SideNoteViewPart
  • view: com.ibm.lotuslabs.sidenote.SideNoteViewPart
  • region: TOP
  • showTitle: true
Figure 7. SideNote
SideNote

This tool is now in the Lotus Notes sidebar.


SideNote actions

Next, let’s take a look at the actions that you added to the SideNote menu: the ability to save the current text to file and to load it from a file.

In the plugin.xml you contribute to one final extension point. This time it is the org.eclipse.ui.viewActions point that allows you to associate some actions with a particular view part. This extension point enables extending not only views you created, but also views that don’t know anything about what you are adding. That is, you could add actions to sidebars that are already in Lotus Notes to extend the functionality of those components. Figure 8 shows how the SideNote plug-in adds these actions. Include the following fields and values in the viewActions extension point:

  • id: com.ibm.lotuslabs.ui.sidenote.actions
  • targetID: com.ibm.lotuslabs.ui.sidenote.SideNoteViewPart
Figure 8. SideNote viewActions extension points
SideNote viewActions extension points

By setting the targetID to the ID of another view, you can contribute actions to that application. For example, using the ID from the Lotus Sametime view in Lotus Notes allows you to extend that component in whatever way you want.

Now that they are associated, you define the actions as shown in figure 9. Include the following fields and values in the viewActions extension point:

  • class: com.ibm.lotuslabs.ui.sidenote.internal.actions.SaveAsFile
  • enablesFor: *
  • id: com.ibm.lotuslabs.ui.sidenote.internal.actions.1.SaveAsFile
  • label: Save As File
  • menubarPath: additions
  • tooltip: Save Side Note text as file
Figure 9. SideNote contributed actions
SideNote contributed actions

These extension points define the label for the actions and point the platform to the code that runs when the actions are selected from the menu. In this case, the extension point contract requires that the class be an IViewActionDelegate. The most important part of this interface is the run() method, which executes the action. The key to making these actions possible is the getText() and setText() methods in the SideNoteViewPart. The run() method for saving and loading uses these methods to perform the requested action.

For example,the SaveAsFile class retrieves the text, allows the user to select a file, and writes it there; see listing 1.

Listing 1. Writing the text to file
	SideNoteViewPart part;
	public void run(IAction arg0) {
		if(part!=null) {
			final String text = part.getText();
			FileDialog dialog = new FileDialog(PlatformUI.getWorkbench().
			getDisplay().getActiveShell(), SWT.SAVE);
			dialog.setText("Save Side Note as:");
			dialog.setFilterExtensions(new String[] { "*.txt", "*.*" });
			final String path = dialog.open();
			if(path!=null) {
				// new job to write to file
				Job write = new Job("Saving Side Note") {
					protected IStatus run(IProgressMonitor arg0) {
						writeToFile(path, text);
						return Status.OK_STATUS;
					}
				};
				write.schedule();
			}
			part.setFocus();
		}
	}

QuickNote toolbar application

The toolbar is another place where you can extend Lotus Notes. The QuickNote toolbar has a button to show a small text box in which you can write notes as shown in figure 10.

Figure 10. QuickNote toolbar
QuickNote toolbar

After you enter your text, you can save it in a folder designated for your notes. Later, you can reload them by clicking the drop-down icon shown in figure 11.

Figure 11. QuickNote menu
QuickNote menu

The com.ibm.lotuslabs.ui.toolbars.quicknote plug-in contributes to the QuickNote application. Note that this depends upon the com.ibm.lotuslabs.ui plug-in, so you need to have both in your Eclipse workspace. The base UI plug-in has been separated out to allow it to provide functionality to several features. In this case, QuickNote uses the simple text box in this plug-in.


Toolbar extension point

Just as you do with sidebar applications, you add toolbar applications to the user interface through extension points. This time, it is the com.ibm.rcp.ui.controlSets extension point. As the menu in figure 12 shows, this single point allows plug-ins to contribute to several places -- toolbar, status bar, and control -- in the Lotus Notes client.

Figure 12. QuickNote controlSets extension point
QuickNote controlSets extension point

To make space in the toolbar near the top of the client or in the status line near the bottom, you add one of the toolBar or statusLine items. In this case, you create a toolBar component. To fill that space, create a control and associate it with the ID you gave the toolbar as seen in figure 13. Specifically, the toolbarPath (com.ibm.lotuslabs.quicknote.bar) in the control element matches the ID in the toolBar element.

Figure 13. QuickNote control extension point
QuickNote control extension point

The class value points it to the Java code needed to build the toolbar. For this extension point, the contract is that this class implements the ISContributionItem interface. The QuickNoteContribution class fulfills this contract.

The key to an ISContributionItem is the fill() method. In this case, you know that you are asked to fill the toolbar given with your buttons. You add two buttons. The first one has the label QuickNote and shows the pop-up text box from the com.ibm.lotuslabs.ui plug-in. The second one is an example of how to create a button with an image. The image is a drop-down icon. You respond to a click on this button by showing a menu.

This menu is populated by reading the contents of the QuickNote folder, which the user selects from the same menu. This same folder is used to save notes taken in the text pop-up box.


Conclusion

These examples should be enough to get you started placing useful components into the Lotus Notes user environment. The flexibility of Eclipse allows you to place just about whatever you want in these locations to enhance the user experience. Also, remember that even though we built SideNote and QuickNote for Lotus Notes, any applications you build on the Lotus Expeditor platform can be reused in multiple clients.

After you build your applications, you need to deploy them to your users. There are some instructions in the "Composite Application Tutorial II: Eclipse Component" tutorial that should help.

In the next article, we take a look at how to integrate and leverage your Lotus Notes data into this environment using the notes.jar library that ships with the product. If you want to get started right away, this entry in the Notes/Domino V8 Public Beta Forum should give you a good start.


Download

DescriptionNameSize
Code samplenotes_extensions.zip26 KB

Resources

Learn

Get products and technologies

Discuss

Comments

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. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. 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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=207334
ArticleTitle=Extending the IBM Lotus Notes V8 sidebar and toolbar
publish-date=04102007