ShowTable of Contents
Introduction
One of the greatest benefits of moving Lotus Domino Designer to the Eclipse platform is better extensibility. Domino Designer defines quite a few extension points that let users create their own custom plug-ins to extend key areas. Although some plug-ins can be found on OpenNTF.org, Domino Designer also leverages Eclipse components like JFace Text Editor and the Eclipse preferences framework.
This document focuses on how to use the rich set of extension points defined by the Eclipse components. We begin by explaining how to set up the development environment and, more specifically, how to use the Lotus Expeditor Toolkit to easily deploy and debug your custom plug-ins.
We then discuss the major Eclipse components and their extension points, followed by a demonstration of how to build a plug-in that extends the new LotusScript Editor, using a real example, that is, a menu that display the list of string literals present in a script library.
Setting up the development environment
To develop extensions for Domino Designer you must install IBM Lotus Expeditor Toolkit. This toolkit provides a framework for developing, debugging, and launching IBM Lotus Notes® and Domino Designer. To extend Designer, users can create plug-in projects based on the Eclipse plug-in wizards or the Expeditor Client Services plug-in wizard.
The following explains how to install and configure the target and launch information. The toolkit uses the configuration information to set up the Java build path and the runtime for your project. Further information regarding the Expeditor Toolkit can be found on the
No-charge products, tools, and toolkits page.
Prerequisites
For Lotus Expeditor Toolkit to function property, you must first install Eclipse 3.2.1 or later. Unlike most other Integrated Development Environments (IDEs), you don't need to run a separate installer for Eclipse; just unzip it to the desired directory and launch the
eclipse.exe file.
Then create a user account with IBM and download
Lotus Expeditor Toolkit V6.2.1.
After downloading, unzip the file into a directory, for example, C:\expeditor\. Then go to the directory where you unzipped Eclipse and launch it from
eclipse.exe.
Once it has launched, select Help > Software Updates. The Software Updates and Add-ons window should appear (see figure 1).
Figure 1. Software Updates and Add-ons window
Installation
The installation steps are as follows:
1. You need to install Lotus Expeditor Toolkit as an update site, so click the Add Site button. The Add Site window displays (see figure 2).
2. Click the Local button and browse to where you unzipped the Lotus Expeditor Toolkit; click OK.
Figure 2. Add Site window
3. Select the Available Software tab and then select Lotus Expeditor Toolkit, as well as any addition packages you may need, and click
Figure 3. Available Software tab
4. Review and confirm that the checked features are the features you want to install; click Next. If you approve the license agreement, click Accept and then Finish.
5. Verify that the Add-ons were installed properly by selecting Help > Software Updates. Click the Installed Software tab and verify that Lotus Expeditor Toolkit is listed (see figure 4).
Figure 4. List of installed software
6. Restart Eclipse. The window in figure 5 displays, in which you can configure the test environment, as follows:
a. Select Lotus Notes 8 from the Test Environment drop-down menu.
b. For the Target Location field, browse to the …\framework\rcp\eclipse directory of your Lotus Notes installation; usually, it's
C:\Program Files\IBM\Lotus\Notes\framework\rcp\eclipse
c. The VM Name field is automatically set to the Notes VM. Click OK.
Figure 5. Test Environment Configuration window
7. The next step is to set up the launcher to launch with your target. The launcher is populated with all the options you need to launch your configured platform. To configure your launcher, select Run > Run Configuration, or Run > Debug Configuration.
8. Select the Client Services launcher and then Create New. Populated the launcher with the information as shown in the Debug Configurations window (see figure 6).
Figure 6. Debug Configurations window
Core Eclipse components extension points
Eclipse core components come with a rich set of extension points that are readily available to extend Domino Designer, the list of which is probably too long to describe in this document. Rather, in this section we focus on a set of key, defined extension points and show how to use the Eclipse IDE to easily find a new one.
If you want to extend the Eclipse user interface, you will most likely use one of the extension points defined in
org.eclipse.ui. Take the time to open the “Plug-in development” perspective and use the Plug-ins view to explore all the extension points provided in
org.eclipse.ui (see figure 7).
Figure 7. Extension points
The
plugin.xml editor is quite useful to access the extension point description or to quickly find other plug-ins that are using the selected extension points and can be used as examples.
If the extension point author has supplied a schema (.exsd), the “Show extension point description” link will display a nicely formatted page that can be used as documentation and as an example to write your own implementation.
For instance, figure 8 shows the description page for the
org.eclipse.ui.editor extension point.
Figure 8. Description page
Here are a few of the most important extension points:
- editors. Adds new editors to the Eclipse Workbench. Editors can be associated with a file using extensions and/or specific file names.
- views. Adds new views to the Eclipse Workbench. A view is the visual component that is contained within a perspective.
- perspectives. Adds new perspectives to the Eclipse Workbench. A perspective defines the views and layout that the user needs to accomplish a set of tasks. Perspectives in Eclipse are customizable.
- PreferencePages. Adds pages to the standard Eclipse preference dialog box.
- actionSets. Adds top-level menus, contextual menus, and toolbar items to the Eclipse Workbench.
In addition, it's worth noting the extension points defined by the
org.eclipse.core.resources plug-in:
- builders. Adds builders to the Eclipse Workbench. Builders are agents invoked to process a set of resources changes.
- markers. Creates markers, which are pieces of information associated with a resource. Markers can be persisted on disk or not. Examples of markers are problem markers, bookmarks, etc.
- natures. Creates project natures, which define life-cycle behaviors for a project. For example, a nature is responsible for associating one or more builders to a project.
Building a plugin for the new LotusScript editor
In this section we build an extension plug-in that displays a list of all the String literals present in a script library, and adds a top-level menu, a toolbar icon, and a contextual menu to the new LotusScript editor. When invoked, this custom menu will display a dialog box with a list of all the string literals present in the script library.
Create a new plugin project
Using the Expeditor toolkit, it's easy to start a new plug-in:
1. Select File > New Project, then expand Plug-in Development and select Plug-in Project. Click Next (see figure 9).
Figure 9. New Project window
2. In the next window, enter the name of the project, for example,
com.ibm.demo.lscript.extension (see figure 10).
Figure 10. Name the Plug-in Project
3. Click Next, then Finish.
Create a new extension point
To create a new extension point of type org.eclipse.ui.editorActions, perform these steps:
1. First we must open the META-INF/manifest.mf file and select the Extension tab.
2. To add an extension, click the Add button (note that, if a
plugin.xml file doesn't exist, clicking the Add button will automatically create it).
3. Select
org.eclipse.ui.editorActions from the list, as shown in figure 11. Click Finish.
Figure 11. Select extension point
A new entry is created in the Extension page of the plug-in manifest editor (see figure 12). Notice all the helpful information about the extension point available in this page.
4. To access the extension point description, click the “Show extension point description” link (provided that the extension point author defined an .exsd schema file for it), as shown in figure 12.
Figure 12. Show extension point description link
The editor makes it easy to implement the extension point by providing contextual menus to add appropriate elements and doing on-the-fly validation. It even automatically creates classes, when needed, saving the developer lots of time.
5. Right-click
com.ibm.demo.lscript.extension.editorContributor, and select New > action (see figure 13).
Figure 13. New action
A new action element is created, and the right-hand pane shows all the needed attributes, including a default value for the required “id” field (see figure 14).
Figure 14. Extension Element Details window
The editor lets you specify the class, even if it doesn't exist yet. Just click on the class header; the “New class” wizard will display to create a skeleton class with the correct interface. NOTE: You can find the icons in the attached project .zip file.
Implement and test the action
We must now implement the CountLiteralStrings action that will look in the current editor and display a list of all the literal strings present therein. The class must extend the
org.eclipse.ui.actions.ActionDelegate class and implement the
org.eclipse.ui.IEditorActionDelegate interface.
There are two key methods that must be implemented:
setActiveEditor(IAction, IEditorPart). Called whenever the editor get the focus. Since the action instance is shared between editors, it is important to remember the current editor in this method.
run(IAction). Called when the action is activated. This method contains the business logic of our extension. Since the editor is based on the standard JFace Text framework, we can expect to access a key interface from the IEditorPart
org.eclipse.jface.text.TextViewer as follows:
TextViewer textViewer = (TextViewer)targetEditor.getAdapter( TextViewer.class );
From the TextViewer, we can access the standard org.eclipse.jface.text.IDocument, which yields lots of information on the current editor.
IDocument uses partitions to differentiate portions of the content with different types. In this case, we want to access the IDocument partitions that matches the “LS_LITTERAL” value, as they correspond to the literal strings we are looking for.
Each partition contains an offset and a length, and we can use the getDocument method to access the content of the partition and display it in a dialog box. The code in listing 1 fills a List object with all the LS_LITTERAL partitions.
Listing 1. Code to fill List object with LS_LITTERAL partitions
TextViewer textViewer = (TextViewer)targetEditor.getAdapter( TextViewer.class );
IDocument document = textViewer.getDocument();
ITypedRegion[] regions = document.getDocumentPartitioner().computePartitioning(0, document.getLength());
ArrayList<String> litterals = new ArrayList<String>();
int numStrings = 0;
for ( ITypedRegion region : regions ){
if ( "LS_LITTERAL".equals( region.getType() )){
numStrings++;
litterals.add( document.get( region.getOffset(), region.getLength() ));
}
}
To test our plug-in, we:
1. Create a new Run Configuration for Domino Designer as described in Section 2 above.
2. Make sure to include the new plug-in in the list of plug-ins that will be loaded.
3. Launch Domino Designer and open a LotusScript library or a LotusScript Agent and verify that the new Count Strings menu displays correctly.
Deploy
For deployment, we must create a feature for our plug-in. To do that:
1. Select File > New > Other, expand Plug-in Development, and select Feature Project. The window in figure 15 displays.
Figure 15. New Feature window
2. Click Next and select the
com.ibm.demo.lscript.extension plug-in, as shown in figure 16.
Figure 16. Select plug-in
After clicking Finish, you should see a new project added to your workspace.
3. Now create an Update Site project for your feature that will be distributed to users for install, by selecting File > New > Others, expanding Plug-in Development, and selecting Update Site Project. The window in figure 17 displays.
Figure 17. Update Site Project window
4. Click Finish, open the
site.xml for the new Update Site, and add the
com.ibm.demo.lscript.extension.feature feature in the site.
5. Finally, click the Build All button. This creates an updated .zip file for distribution that users can install using the Eclipse Update Manager.
Figure 18 shows the newly added menus.
Figure 18. Added menus
Figure 19 shows the dialog box displaying the list of literal strings.
Figure 19. Number of strings found
Source code attachment
The attached .zip file contains the following:
- Plug-in source code
- Feature project
- Update Site project
You can install these into your Expeditor workspace by selecting File > Import > Existing Projects into Workspace. Then select the Archive File radio button and choose the attached zip file.
Conclusion
The new LotusScript Editor available in IBM Lotus Domino 8.5.1 is based on the Eclipse JFace Text framework, enabling users to leverage the rich set of extension points already provided by Eclipse to extend the editor and add meaningful functionality.
We first discussed the list of extension points provided by the JFace Text Editor, and then used an actual end-to-end example to illustrate the steps to create, test, and deploy the plug-in. The example showed how to add a top-level menu, a toolbar icon, and a contextual menu to the LotusScript editor providing information on the list of literal strings present in the current editor.
Moreover, the example can be used as a starting point for a more enhanced tool that can help localize a LotusScript application.
Resources
Lotus Domino Designer 8.5.x documentation:
http://www.ibm.com/developerworks/lotus/documentation/dominodesigner/
developerWorks Lotus Notes and Domino product page:
http://www.ibm.com/developerworks/lotus/products/notesdomino/
developerWorks Lotus Expeditor product page:
http://www.ibm.com/developerworks/lotus/products/expeditor/
Lotus Notes/Domino 8.5 forum:
http://www-10.lotus.com/ldd/nd85forum.nsf?OpenDatabase
Lotus Expeditor Forum:
http://www-10.lotus.com/ldd/expforum.nsf?OpenDatabase
Download Lotus Domino Designer:
http://www.ibm.com/developerworks/downloads/ls/dominodesigner/
About the authors
David Taieb is a Senior Software Engineer based at IBM's Massachusetts Software Labs. He started in 1996 in the International Product Development group, working on a globalization tool for the Notes/Domino application, Domino Global Workbench. He then pursued his interest in Java technologies like J2EE and Eclipse, working in various WebSphere Portal-related products.
In 2006, he worked on the IBM Lotus Mashup responsible for integrating OSGI equinox into the product, and then worked on IBM Lotus Designer as the architect for the new LotusScript editor on Eclipse.
Yung Chen is a Software Engineer based at IBM's Massachusetts Software Labs. He has been involved in applications development for Domino Designer, Notes APIs, and various Notes development projects. You can reach him at
chenyung@us.ibm.com.
Roberto Olivares is a Software Engineer based atIBM's Massachusetts Software Labs. He works on Domino Core Services including OS layer development, serviceability development, performance engineering, and anti-spam SPF extensions for Lotus Domino. He's the Intel/Lotus Development Liaison and a key contributor to the LotusScript editor on Eclipse for Lotus Domino Designer 8.5.1.