Sidebar Contribution Design Pattern
This document discusses the Notes 8 “shelfViews” programming model, and explicitly explains how to contribute a shelf view to the Notes 8 sidebar. There are basically two steps:
Following these descriptions, we compare the Notes 8 “shelfViews” programming model to the Sametime “miniApps” programming models, such that developers will know how to migrate a plugin from the Sametime client to the Notes 8 client.
- Create a view and add a contribution to the org.eclipse.ui.views extension point.
- Contribute the view to the com.ibm.rcp.ui.shelfViews extension point to have it appear in the sidebar.
The Notes 8 “shelfViews” Programming Model
Notes 8 makes use of the eclipse IViewPart interface to be able to tie each shelf view to the workbench. Each view part has a view site that connects the part to the workbench, allowing the view to register any global actions with the site’s action bars, including access to its own panel menu, a local toolbar, and the status line. The view can also register any context menus with the site, or register a selection provider to allow the workbench’s ISelectionService to include the part in its tracking. The workbench also provides other capabilities, such as saving the state of the view, or activating these shelf views upon accessibility.When creating a view to be shown in a Notes 8 shelf view, the class should either implement the interface, org.eclipse.ui.IViewPart, or subclass the abstract class, org.eclipse.ui.part.ViewPart. Subclassing ViewPart is the suggested method, to save the developer from implementing the view from scratch. Subclasses of ViewPart must implement the following methods:
- createPartControl(Composite parent) – to create the view’s controls
- setFocus() – to receive focus
After creating the class, a contribution to the org.eclipse.ui.views extension point must be added to the plugin.xml file for the plugin, as seen in the following example:
Make sure the following attributes are specified:
- The “name” attribute describes the String to be displayed in the titlebar.
- The “id” attribute is the unique identifier of the view. This is also what is used to refer to the view when contributing to the shelfViews extension point.
- The “class” attribute specifies what class is referenced in this extension
- The “icon” attribute describes the icon to be displayed in the top left corner of the titlebar. The standard size is 16x16 pixels.
The view should be optimally viewed in a frame approximately 186 pixels wide. The view is also resizeable. Thus, make sure the content can be scrolled (if applicable), and any toolbars do not get cut off, or have chevrons pointing to more actions.
Contributing to the shelfViews extension point
In the plugin where the view is defined, add an extension to the com.ibm.rcp.ui.shelfViews extension point as demonstrated in the following example:
<!-- first define view -->
<!-- next, define shelf view -->
<!-- notice that the com.ibm.rcp.ui.shelfViews "view" attribute corresponds to an org.eclipse.ui.views "id" attribute -->
Note that the com.ibm.rcp.platform.shelfViews extension point has been deprecated.
The “id” attribute uniquely identifies the shelf view. Thus, if the same id is used more than once, only one of those views will be registered.
The “view” attribute corresponds to the “id” specified in the view contribution.
The “region” attribute is an optional means of describing what area of the sidebar the view should belong to. Possible values are “TOP,” “MIDDLE,” and “BOTTOM.” Items within the same placeholder region will be ordered based on when the view gets loaded. Thus, the contributor of the view cannot control the placing of views within the same placeholder region. If nothing is specified, the view will automatically be placed on the bottom.
The “page” attribute describes which sidebar the view should belong. For Notes 8, the value “RIGHT” should be specified such that the view appears in the sidebar on the right side of the client.
The “showTitle” attribute describes whether or not the titlebar should be shown. For Notes 8, a value of “true” should be specified such that all views in the sidebar have a titlebar and look uniform.
Notes 8 “shelfViews” vs. Sametime 7.5 “miniApps”
Similar to Notes 8’s use of eclipse’s IViewPart interface and ViewPart abstract class for its shelf views, Sametime 7.5 uses the abstract class, com.ibm.collaboration.realtime.miniapp.AbstractMiniApp, to create the views displayed in the Sametime client. The API for AbstractMiniApp and ViewPart are similar but have some important differences, as seen in the following selection of the API:
|AbstractMiniApp API||Corresponding ViewPart API |
public abstract Control createControl(Composite arg0);
public IWorkbenchPartSite getSite();
public abstract void init() throws Exception;
public Boolean isInitiallyVisible();
public void setSite(IWorkbenchPartSite site);
public abstract void createPartControl(Composite arg0);
public IViewSite getViewSite();
public void init(IViewSite site) throws PartInitException;
public void init(IViewSite site, IMemento memento) throws PartInitException;
public void setSite(IWorkbenchPartSite site);
As mentioned earlier, a ViewPart has a createPartControl(Composite) method in which the view’s controls are created. Similarly, an AbstractMiniApp has a corresponding method, createControl(Composite). Unlike the ViewPart, however, the AbstractMiniApp does not require a view site upon initialization. The ViewPart must have a view site in order to tie the part to the workbench, thus it is a parameter in the init methods. Since the Sametime views do not require that upon initialization, the Sametime views are rather independent parts of the Sametime workbench, and are not connected to workbench-related features, such as the action bars mentioned previously.
As a result of these differences, it will be somewhat seamless to migrate a Sametime mini app to Notes 8, but not necessarily vice versa. A mini app class has the basics needed to support a ViewPart, but a ViewPart may be supporting connections to workbench-related capabilities that will not be supported if placed in the Sametime client.
Steps for Migrating a Sametime 7.5 plugin over to Notes 8
1. In the plugin.xml of the Sametime plugin, find the extension to the com.ibm.collaboration.realtime.imhub.miniApps extension point. Find the source code for the class specified in the “class” attribute. In the following example, this would be the TaskListMiniApp.java file located in the com.ibm.webahead.stplugins.tasklist.plugin package.
2. If the class extends org.eclipse.ui.part.ViewPart, no changes need to be made, and you may skip to step #4. If it extends com.ibm.collaboration.realtime.miniApp.AbstractMiniApp instead, replace AbstractMiniApp with ViewPart, and import the required methods. A createControl(Composite parent) method should already exist. Modify the newly added createPartControl(Composite parent) method to call createControl(parent).
3. Go back to the plugin.xml file. Add an extension to the org.eclipse.ui.views extension point.
Notice that the “class” attributes for both the miniApps extension point and views extension point are the same. The “name” attribute is the string that will be displayed in the titlebar of the panel. The “id” attribute is the unique identifier, and will be used to identify the view when contributing to the shelfViews extension point.
4. Finally, add an extension to the com.ibm.rcp.ui.shelfViews extension point, detailed further in the section “Contributing to the shelfViews extension point” section.
Migrating a Sametime 7.5.1 plugin over to Notes 8
Sametime 7.5.1 plugins follow the Notes 8 shelfViews programming model. Thus, no further changes should have to be made and installing the plugin should be sufficient.
Installing new plugins in Notes 8
By default, the policy for enabling the display for the user-initiated updates application install menu is set to false (hidden). When set to true, the menu will be rendered visible. This can be updated using the Domino 8.0 desktop policy as described in the Beta 2 release notes.
In cases where Domino is not deployed, it is possible to manually enable this setting on the client. This can be done by updating the <notes_home>\framework\rcp\plugin_customization.ini file to include the following property: com.ibm.notes.branding/enable.update.ui=true.
The value specified in the plugin_customization.ini file acts as a default value when no policy has been set. If the Domino desktop policy sets the user-initiated updates preference, it can be locked-down and will override any existing value specified in the plugin_customization.ini file.
When the enable.update.ui preference is set to true, users will see the following Install and Application Management menu items shown in the screenshot below. Please note that the location of these menu items may change for the general release.
Things you need to know about the B... (Jan Kenney 8.Mar.07)
Feedback response number CWOT6ZFLGX created by Craig Wolpert on 03/19/2007
. . Release notes (updated on 23 May) (Jan Kenney 9.Mar.07)
. . . . New in beta 3? (Per Jonsson 24.May.07)
. . Productivity Tools User Guide (Jan Kenney 9.Mar.07)
. . . . Productivity Toolkits for Notes 8 B... (Mika Heinonen 10.Mar.07)
. . . . . . Correct (Robert Ingram 10.Mar.07)
. . . . . . Correct - productivity editors are ... (Ed Brill 10.Mar.07)
. . Domino 7 install Guide (also applie... (Jan Kenney 9.Mar.07)
. . REQUIRED Patch for Domino 8 - Domin... (Jan Kenney 9.Mar.07)
. . System Requirements for Notes and D... (Jan Kenney 9.Mar.07)
. . . . System Requirements for iSeries (Rob Berendt 19.Mar.07)
. . . . . . 5722 AC3 pre-req will be removed. (Barbara Foss 27.Mar.07)
. . Download Files (Jan Kenney 9.Mar.07)
. . How to report Notes 8 Beta issues a... (Jan Kenney 10.Mar.07)
. . Composite Applications Tutorial and... (Jan Kenney 10.Mar.07)
. . Reviewer's Guide for Notes and Domi... (Jan Kenney 12.Mar.07)
. . Domino 8 - Information and known is... (Jan Kenney 15.Mar.07)
. . Activities update (Jan Kenney 15.Mar.07)
. . Application Development Articles - ... (Craig Wolpert 19.Mar.07)
. . . . Article - Designing Composite Appli... (Craig Wolpert 19.Mar.07)
. . . . Article - Developing Composite Appl... (Craig Wolpert 19.Mar.07)
. . Documentation -- Sidebar Contribut... (Craig Wolpert 19.Mar.07)
. . Documentation -- Sidebar Contribut... (Craig Wolpert 26.Aug.08)
. . C API toolkit for 8.0 are now avail... (Jan Kenney 5.Apr.07)
. . Where are the Linux Patch notes? <e... (Len Berg 19.Apr.07)
. . Documentation - Extending the IBM L... (Craig Wolpert 22.Apr.07)
. . . . Except a bunch of the doc is outdat... (Nathan T. Freem... 23.Apr.07)