Introduction

IBM Notes 8.5.x provided users with a collection of Search Engines to search across Mail, Calendar, Contacts etc. It also supported integration of third-party search engines into IBM Notes Search Center. Any search engine contributed to search center shows the results in the separate search page.

However this search page was not able to render customized search query UI contributions. Users would also like to leverage their customized search engines to bring up search results right within the Mail File.

This article explains how the new enhancements can be utilized to provide both of these functionalities.

Setup

a) You need to setup your Java development environment for IBM Notes. Please use the links given in references for any help.

b) To follow the examples in the article, 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.

Rendering custom search engine results in Notes Mail Views

This enhancement applies to search engines that work against Notes documents.

As you may know, we can contribute customized UI to PIM applications via RCPContentspots. You can read more about it here : “Customizing PIM views in IBM Notes V8.5 using “Content Spots"

The cited example uses the same RCPContentspots framework to contribute two buttons to the Mail UI.

Figure1: Buttons to invoke and clear search in the current Mail view.

To see this contribution in your Notes Mail, you need to add following extension to your plugin.xml



The “class” attribute should be a class that extends “com.ibm.rcp.contentSpots.AbstractContextSpotContrib”. In our given example the class is SearchControlContrib.java

To render search results within the existing mail view, the SearchControlContrib.java uses the two new APIs from the interface “com.ibm.csi.IRuntimeDelegate.java”

1. setSearchResults(IRuntimeFolder rtFolder,Object idType ,List idList)
2. resetSearchResults(IRuntimeFolder rtFolder)

Note:
To use these APIs you need to add the highlighted plugin's as a dependancy to the manifest.mf of your pluign.


Figure2: Adding dependency to your plugin.

Setting the search results

On clicking the search button, the custom search algorithm can be invoked in the background to compute search results. The result set is expected to comprise noteids/unids for individual documents in the result set. These noteids/unids should be part of the current Notes view. Such a list of noteids/unids should be passed to the API mentioned below. This API would enable the rendering of the search results right in your existing mail view.

public void .setSearchResults(IRuntimeFolder rtFolder,Object idType ,List idList) throws ServiceException;


Note: In the sample plugin provided, SearchControlContrib.java is the class which invokes this API with a dummy noteid. This noteid may not exist on your system. Prior to trying the sample plugin, you would need to change its value to a valid noteid for any document in your current mail view(e.g If your current selection is on Inbox, the noteid passed should be of a document that is in the Inbox)


On clicking “Reset Search” button, the selection Listener makes the following API call:

public void resetSearchResults(IRuntimeFolder rtFolder)throws ServiceException;

This call clears the search results displayed and restores the original contents of the view.

Adding customized Search Query UI to your Search Page

The IBM Notes Search Center allows for contribution of custom search engines. For the new search engines added here, search results are displayed in a new search page tab. To understand how to add contributions to the search center please read here: “Customizing your IBM Lotus Notes 8.5.x search environment”

The sample plugin contributes “My Search” custom search engine to Notes Search Center. It basically runs Full Text search on Notes documents using Notes Java APIs . “com.ibm.search.demo.searchengine.MySearchEngine.java” is the class which implements com.ibm.rcp.search.engines.SearchEngineDelegate, and has the logic coded for this search engine.

Note: This is not the search engine built with full functionality for searching Notes documents. It is just a sample code to demonstrate the use of new APIs. Notes Application Developers can have their own sophisticated engine which replaces the “My Search” engine.

Figure3: Custom search engine “My Search” contributed to search center.


For this search engine IBM Notes 9.0 allows the addition of custom search UI to the Search Page.
It is seen as in the figure below:


Figure4: Custom search query UI contributed to search page.


This contribution can be done in the the same way as RCPContentSpots can be used to make UI contributions to the Mail. A new “content spot” called – "com.ibm.rcp.search.ui.internal.views.SearchView.afterActionBar" is introduced in Notes 9.

Apart from this, no other changes to the "com.ibm.rcp.contentSpots.extension" extension point are needed.



On clicking the search button from custom search control UI, we want “My Search” engine to execute its search logic and render results in the same search page.

To achieve this we need to call the following code from SearchViewContrib.java



Note: The search performed using custom search query UI will not be shown in “Recent Searches” as part of search history.

Other Advanced Search customizations

Hiding the existing search control:

Adding a custom search query UI to the search page means that both the new UI and the existing search control are visible (as seen in figure 4). To avoid the possible confusion and improve the user experience, it is possible to hide the existing Search Control, using another new API introduced.
In order to use this API, we now have a new interface “com.ibm.rcp.search.engines. AdvSearchEngineDelegate” that is to be used instead of the “com.ibm.rcp.search.engines.SearchEngineDelegate”.

The AdvSearchEngineDelegate extends the SearchEngineDelegate(that provides functionality to create a simple interfaces between an already-existing search engines and the Notes Search Center).

The new interface has the following method that is to be implemented to hide the existing search control:


public boolean isHideSearchControl();


In the sample plugin provided, “com.ibm.search.demo.searchengine.MySearchEngine” implements “com.ibm.rcp.search.engines.AdvSearchEngineDelegate” to hide the existing search control as shown below:


Figure5: Default Search Control is hidden and only custom search UI is visible.

Hiding the Search History via policy:

The Search History shown in the Notes Search Page under “Recent Searches” can be hidden via the following notes.ini setting (which can be pushed via policy settings):
HideSearchHistory = 1


Because of this ini setting, Notes preference page will de-select the “Search History” preference as highlighted below.


Figure6: “Enable History” preference is not selected.


To enable “Search History” back, user needs to explicitly select this preference. User's explicit action of making Search History visible will override the notes.ini parameter and the Search History will display.

Including custom search UI from search page in Notes Mail

The same search query UI as shown in figure 4, can be included in the Notes Mail file as shown below in figure 7.

It uses again the RCPContentspot framework and the same “com.ibm.search.demo.ui.SearchViewContrib” class as discussed earlier.

Clicking the Search button launches the search page and uses “My Search” engine for computing the results. The advantage of this integration is: custom search UI from mail file can directly talk to a search engine contributed to Notes Search Center. Also users don't have to wait for the search page to get launched, to see their custom search UI.

Figure7: Custom search UI contributed to search page can also be integrated to Notes Mail View.

Conclusion

This article explained in detail the new APIs and extensions introduced in IBM Notes 9.0 for custom search UI integration. These enhancements will help Notes Application Developers to build a better customized search experience.

References

• Read the article on the steps for “Running Notes from the Eclipse IDE."
• Read the article on “Using IBM Lotus Expeditor Toolkit."
• Read the article on “Customizing your IBM Lotus Notes 8.5.x search environment”
• Read the article on “Customizing PIM views in IBM Notes V8.5 using “Content Spots"
• Read the developerWorks article, “Creating a Notes/Domino plug-in with Eclipse.”
• Read the developerWorks article, “Extending the IBM Lotus Notes V8 mail with Eclipse
• Read the IBM Redbooks® publication, "Leveraging Notes-specific APIs."

About the author

Snehal Devasthali is working with IBM - India Software Labs, as a System Software Engineer. She is a Notes client developer and her interests are Java and C++ programming. You can reach her at snehal.sd@in.ibm.com.