![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
In a previous article, "Extending the IBM Lotus Notes V8 sidebar and toolbar," you learned how to contribute your own components to the IBM Lotus Notes V8 user experience. In "Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar," you learned how to have the sidebar and the toolbar access Lotus Notes data to make them more useful.
The Journal toolbar and SideNote you created are very useful for quickly saving and accessing random thoughts that you want to write down quickly. If you used these tools, however, you may have noticed that often thoughts aren't so random. These quick notes are usually about something you have been working on and maybe even about what you are looking at right then on the screen. What if you could link those thoughts to their source?
In the previous article, "Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar," you used notes.jar to save information to the journal so that you don’t create yet another data repository on your desktop. If you could easily link these disparate sources of these documents to the documents themselves, you could reduce this problem of information scatter even more.
The new Eclipse-based architecture of Lotus Notes makes this linking possible. The platform allows you significantly increased visibility of what the user is doing at any given moment. You can leverage this information to create more effective tools and applications. This article explains how to access the user's current context and further extends the applications you have created in the two previous articles to use this new information.
First, you need to install the Lotus Notes V8 software. 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.
Open Eclipse, and set the target platform by doing the following:
- Choose Window - Preferences.
- Expand Plug-in Development.
- Select Target Platform.
- In the Location edit control, type or browse to C:\Program Files\IBM\Lotus\notes\framework\eclipse.
- Click the Reload button, and then click OK.
Next, you create an additional installed JRE:
- Choose Window - Preferences.
- Expand Java.
- Select Installed JREs.
- Click Add.
- For JRE name, enter Notes JRE.
- 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:
- Choose Run - Run, and then select Eclipse Application.
- Right-click and choose New.
- Enter a name (for example, Notes).
- Under Program to Run, select Run a product, and then select com.ibm.notes.branding.notes.
- In the Runtime JRE, select Notes JRE.
- 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:
- Click Variables.
- Click Edit Variables.
- Click New.
- Enter notes.install for the name.
- Enter the path where you installed Lotus 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.
- Repeat steps 1 to 3.
- Enter notes.data for the name.
- 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. - Repeat steps 1 to 3.
- Enter rcp.base for the name.
- 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 is com.ibm.rcp.base_6.1.1.200705170110. - Click OK, and then click Cancel to the Select Variable dialog box (if you click OK to select the variable, it adds the variable at the insertion point).
To enable Notes security from Eclipse, 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, choose 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.
- Choose File - Import.
- Select General - Existing Projects into Workplace, and then click Next.
- Browse and select the folder that you unzipped the code to and click OK.
- Click Finish to complete the import process.
The Eclipse platform is made of several layers and gives plug-ins the ability to listen to what is going on in each of these layers. By adding listeners, you can be notified of the user's current context as it changes.
The com.ibm.lotuslabs.context.service plug-in has been created to add just one more layer to what Eclipse provides. In particular, the DocumentContextService allows other plug-ins to subscribe and to be told when the user changes documents within the Lotus Notes client.
At any given time, the context is described as the current selection within the current IWorkbenchPart. The Eclipse platform states that the current part should publish its selection by defining an ISelectionProvider and setting it through its site: part.getSite().setSelectionProvider().
The IWorkbenchWindow that contains, among other things, the perspectives and parts where the selection is changing can obtain an ISelectionService that tells you when changes occur. This service allows you to add two different types of selection listeners. If you use the addSelectionListener() method, you are notified immediately whenever the selection changes. If you use the addPostSelectionListener() method, though, it pauses briefly on keyboard navigation to make sure the user comes to rest on that item. The DocumentContextService uses addPostSelectionListener to minimize superfluous notifications.
DocumentContextService also allows two types of listeners in a similar fashion. If a consumer uses the addSelectionListener() method, it is notified every time the selection changes. If the addListener() method is used, the consumer wants to know only when a new document is selected. The service defines that a new document is selected when the new selection has a different URI than the current one.
To make it simple for the consumer, the service first registers itself as an IWindowListener to be notified when a new window opens. To that new window, it adds a selection listener to its selection service. Through this mechanism, the selectionChanged() method in the DocumentContextService class is called every time the user changes the selection. This method determines if this is a new document and notifies its consumers as appropriate with the current DocumentSelection.
DocumentSelection is a class for the service used to represent a collection of documents. Each document provides information about itself through an IDocumentContext object. The interesting logic in this plug-in concerns how to convert the selection given by the Eclipse platform.
Unless overridden for a specific object, this conversion happens within the constructor of the internal DocumentContext class. The key to extracting relevant information is the Eclipse concept of IAdaptable.
This flexible framework allows any object to be translated into another type. The translation can happen either directly or indirectly. It can be translated directly either by being that type of Object or by implementing IAdaptable. It can be done indirectly through the platform and the use of the org.eclipse.core.runtime.adapters extension point. Therefore, to make the translation from one Object to another, you can use the code shown in listing 1.
Listing 1. Extracting an adapter out of a given Object
public static Object getAdapterObject(Object o, Class clazz) {
Object item = null;
if(clazz.isInstance(o))
item = o;
else if(o instanceof IAdaptable) {
item = ((IAdaptable)o).getAdapter(clazz);
}
if(item==null) {
IAdapterManager man = Platform.getAdapterManager();
if(man!=null)
item = man.getAdapter(o, clazz);
}
return item;
}
|
The DocumentContext uses the getAdapterObject() method to determine the title, URI, icon, and properties of the selected Object. First, it attempts to use the IURIProvider that Lotus Notes uses to know what to bookmark. It provides all these items. If it is unable to find the title or icon, it uses the IWorkbenchAdapter interface, which may have these details. If there is no URI, it tries to adapt the Object directly to the URI class. Finally, it tries to figure out other various properties using the IPropertySource interface. If these techniques fail, DocumentContext returns to using information from the current IViewPart.
The provided com.ibm.lotuslabs.context.ui.test plug-in contributes a sidebar panel that shows what the DocumentContextService is reporting as the current document. See figure 1.
Figure 1. Context sidebar
The com.ibm.lotuslabs.todo.ui plug-in contributes a toolbar that is another extension of the SideNote concept and the Journal toolbar from the previous articles. The Todo toolbar lets you launch the Todo application, show the new task form, or quickly create a task as shown in figure 2. The difference is that this toolbar uses the DocumentContextService to create a task that refers to the current document.
Figure 2. Creating a quick task
This notion of creating a task about or from the current document should increase productivity because it increases coupling between applications. The new task that is created has the text you typed and a link to the originating document. See figure 3.
Figure 3. New task with link
Everything about this toolbar contribution is the same as the Journal toolbar from the previous article, "Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar," except for the ability to add this link. As an instance variable, the TodoContribution class keeps current DocumentSelection. When the toolbar is created, it adds a listener to the service as shown in listing 2.
Listing 2. Adding the DocumentContextService listener
final IDocumentContextListener listener = new IDocumentContextListener() {
public void selectionChanged(IWorkbenchPart part, DocumentSelection selection) {
current = selection;
}
};
final DocumentContextService service = DocumentContextService.getDefault();
service.addListener(listener);
|
Now when the dialog box is shown, it can use this selection Object to produce a link item. When the user selects Quick, it extracts the title and URI from the selection. The SideNote object has the ability to set the text for a check mark and see if the option was checked when the user closed it.
Whether the user selects the option or not, the code uses the com.ibm.lotuslabs.notes.pim plug-in to create the task. Specifically, it calls the TodoTask.createTask() method. As inputs, this takes in the text and title of the new task. Additionally, it can take an array of links for inclusion above the text.
The createTask() method uses the NotesJob framework that was discussed in "Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar." Just as you do when you create a journal entry, you have to create a new document with the right items. Specifically, you set title and body, and you complete the other fields that the Task form is looking for such as importance, due date, and others.
As you create the body, you can add the links that were passed in. The code in listing 3 shows how that is accomplished.
Listing 3. Creating the task body
RichTextItem body = doc.createRichTextItem("Body");
// if links
if(links!=null) {
for(int i=0;i<links.length;i++) {
addLink(session,body,links[i]);
}
body.addNewLine();
}
body.appendText(val);
|
The addLink() method allows any String to be used as a link. The method checks specifically for the notes:// URL. If this is found, it creates a custom Lotus Notes link; otherwise, it just adds the link itself to the text.
SideNote is an application in the sidebar that provides a single place to write down text. It is not really intended to be saved, though. Journal It uses the same location, but a different approach. Journal It gives you a saved note for each document instead of the single note. See figure 4.
Figure 4. Journal It application
Taking notes in Journal It links the entry to the current document. The user can take notes in the sidebar about an email. From that point on, those notes appear every time that email is on display.
The com.ibm.lotuslabs.journal.ui.context plug-in contributes the JournalCurrentViewPart part to the Lotus Notes sidebar. This ViewPart subscribes to the DocumentContextService to know when the user switches documents. The URI of the document is mapped to an ID. This ID is used to look up a document in a view in the journal database. If it does not exist, Journal It uses the title from the service. If the user actually changes anything, the data is saved using that ID.
The actual display of the journal entry uses the JournalNote Composite in the com.ibm.lotuslabs.notes.pim plug-in. The challenge of having a UI component like this that is backed by Lotus Notes data is handling the threading issues. That is, you cannot connect to the journal database from the UI thread.
JournalNotes handles the thread issue by having a static method called createValueMap() that takes in a Document Object and fills a Map with what is needed to initialize the UI. This Map is created in the NotesJob so all the hard work is done within this other thread. Then the Map can be passed to the UI thread to create the control.
Before this Map can be created, however, the document has to be found in the view. The JournalIt view is created the first time it is needed by the createSidebarView() method in the JournalSidebarUtil class. This view shows all documents in the database that have the JournalIt ID field. Furthermore, when this view is being created, the other views in the database are updated to not show these documents. This action keeps the By Category view the same to the user. The lookup uses the view.getDocumentByKey() method using the mentioned ID value.
When the document service notifies it about a new document, the application checks to see if the user changed anything. If something has been changed, a new journal entry is created or the previous one modified with the subject and text.
IBM Lotus Notes V8 has a few limitations; the main one is that the title of the selected document is incorrect when it is selected in a non-PIM view. Specifically, the DocumentContextService reports that the title of the document is the title of the view.
The other problem is that the service is not currently reporting the URL of the Web sites that the embedded browser is viewing. One of the main benefits of using Eclipse interfaces is that all types of components can participate. The embedded browser just needs to report its selection through its IViewPart. After this happens, applications such as Journal It work across Lotus Notes documents and Web pages and anything else that reports their selection.
Over the last three articles, we've looked at how to insert components into the Lotus Notes user interface, how to access and modify Lotus Notes data, and how to take advantage of the user’s context. By putting together all of these capabilities, you can make some exciting applications.
In particular, this concept of tailoring your application to what the user is doing at that moment is powerful. The services and samples provided in this article should help you get started.
| Description | Name | Size | Download method |
|---|---|---|---|
| Sample code | context.zip | 55 KB | HTTP |
Information about download methods
Learn
-
Watch a brief demo of sidebar and toolbar journal integration.
-
Read the developerWorks article, "Extending the IBM Lotus Notes V8 sidebar and toolbar."
-
Read the developerWorks article, "Integrating IBM Lotus Notes data into the Lotus Notes V8 sidebar and toolbar."
-
Read the forum posting on Notes.jar.
-
Read the developerWorks article, "What's new in IBM Lotus Notes and Domino V8."
-
Read the developerWorks article, "The new IBM Lotus Notes V8 Out of Office functionality."
Get products and technologies
-
Download Eclipse.
Discuss
