Component API-Create component viewparts programmatically

Abstract

ShowTable of Contents

HideTable of Contents

1 Access the API
2 Sample application
3 Requirements
4 Opening NSF viewparts
5 Download link

The Component API provides access to the most relevant APIs for Composite Application development and automation. This includes wrappers for the TopologyHandler to define new components (e.g. NSF viewparts that display Notes data like views or documents), which also work outside of a Composite Application context, and a few helper messages that provide shortcuts for frequently used functions..

Access the API

The base class of the Component API is called IRemoteComponentTools. It can be retrieved from the ComponentAPI class with the following code snippet:

var conn=X2E.createConnection();
var compTools=com.x2e.ComponentAPI.getTools(conn);

Sample application

The sample for the Component API demonstrates how Eclipse viewparts can be created programmatically, in this case to display Lotus Notes design elements like documents and views.

It contains a Composite Application with two components: an information page in the main display area with instructions and a sidebar component that contains the actual code.

The sidebar component is defined to be always visible when the Composite Application's database is open, even if the database tab is not focused. This makes it possible to use its functionality in other databases as well, as long as the Composite Application is not closed.
Please note:
For Lotus Notes 8.5.2, displaying an XPage in the sidebar is something that is only possible when using Composite Application technologies (that's why we're using a CA here). There are plans for Lotus Notes 8.5.3, to support XPages widgets in the sidebar without the need to create a CA.

There are two buttons in the sidebar component. Both will get enabled after a target Eclipse perspective (the tab on which the content should be displayed) has been selected via the magnifier icon.

Sidebar Component picklist

1. Open selected documents in perspectiveThis feature reads the document selection from the current Notes view and opens a viewpart for each document in the selected target perspective. You can then drag&drop those viewparts, e.g. to compare two or more documents side by side.

2. Open current viewpart in perspectiveThe second feature tries to find an open UI view or document and creates a new viewpart with the same content in the selected target perspective. This is useful to mix data from different databases on the same tab.

The sample application does not only make use of the Component API, but also uses a few other APIs like the NotesUI API, Perspective API and the PlatformUI API. The main code is written (and documented) in two Java classes which you can find in the Java perspective of Domino Designer.

Requirements

The sample application requires the XPages Extension Library

to be installed in addition to the XPages2Eclipse plugins. It is leveraging the Value Picker Control of the Extension Library to easily let the user select the target Eclipse perspective.

Opening NSF viewparts

Since the sample is rather complex (the code is well documented), we'll concentrate on the most relevant code snippet: creating a new NSF component on the current workbench page.

var conn=X2E.createConnection();
//use PlatformUI to get a handle on the active workbench page
var pUI=com.x2e.PlatformUIAPI.getUI(conn);
var wb=pUI.getWorkbench();
var activeWindow=wb.getActiveWorkbenchWindow();
var activePage=activeWindow.getActivePage();

//access the TopologyHandler, a kind of registry for CA components
var compTools=com.x2e.ComponentAPI.getTools(conn);
var topologyHandler=compTools.getTopologyHandler();

//the primary id is the same for all NSF viewparts

var primaryIdNSFPart="com.ibm.workplace.noteswc.views.NotesViewData";

//create a new random ID for the specific new viewpart instance; Eclipse uses the secondary ID to uniquely identify a viewpart

var secondaryId="X2ESample_"+java.util.UUID.randomUUID().toString().hashCode();

var params=new java.util.HashMap(); //there are a few more supported values that just the Notes URL (e.g. //the title, see the component properties panel of Composite Applications //for other property names), but the URL is enough for now params.put("com.ibm.notes.notesurl", notesUrl); //add your Notes URL in here, e.g. pointing to a document, view or frameset //register the component properties at the TopologyHandler for the new secondary id topologyHandler.modifyComponent(params, thisSecondaryId);

//finally tell the workbench page to display the new viewpart

activePage.showView(primaryIdNSFPart, secondaryId, com.mindoo.remote.api.org.eclipse.ui.IRemoteWorkbenchPage.VIEW_VISIBLE);

As you can see in the code, you need two IDs to define and display a new component: the primary and the secondary ID. The primary ID contains the type of the viewpart, in our case "com.ibm.workplace.noteswc.views.NotesViewData". This string cannot be changed, if you want to display NSF data, because that's how the specific Java component is registered in the Eclipse platform.

To create unique instances of the same viewpart type, we need another string, the secondary ID, which Eclipse uses to identify the specific instances.

When the NSF viewpart get's displayed, it asks the TopologyHandler for its component parameters that are used for the view's rendering process. That's the reason why we call IRemoteTopologyHandler.modifyComponent before opening the view via the IRemoteWorkbenchPage.showView() method.