ShowTable of Contents
Introduction
IBM Notes V8 embraced the IBM Expeditor platform, which helped IBM Notes become customizable and extensible. Because IBM Expeditor is based on the Eclipse platform, it has become very easy to contribute new custom UI to Notes, in a separate Tab.
Often these custom UIs are related to IBM Notes PIM views (Mail, Calendar, Contacts, To Do, Notebook, Day-At-A-Glance). Hence there was consistently a need reported by many Notes application developers to add their custom UI, directly to Notes PIM views rather than in a separate tab because switching between the tabs is really frustrating for the end user. Also many users prefer to live in their Mail view. In that case they are reluctant to go to a different tab which has custom UI related to Mail/Calendar. Using this integration the custom UI can reap the benefit of having direct interaction with the Notes PIM views from the same tab.
“Rich Client Platform(RCP) Content Spot” is the new framework designed to achieve this functionality. Using this framework Notes PIM views can now accept UI contributions. Also any Java views seen in Notes can use this framework to become more extensible.
Setup
a) You need to setup your Java development environment for IBMNotes. 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.
1. Choose File-Import.
2. Select General – Existing Projects into Workplace, and then click Next.
3. Browse and select the folder that you unzipped the code to and click OK.
4. Click Finish to complete the import process.
Introduction to “RCP Content Spot” framework
IBM Notes 8.5.x introduced a framework called as “Content Spot” for Rich Client Platform. This framework is the foundation for integrating customized user interfaces to Notes based Java views.
What is a “Content Spot”?
Every unique location in a Notes based Java view, where custom UI can be contributed, is termed as a “content spot”.
One such example is of Notes Mail, which has 3 predefined “content spots” :
a) After Action Bar
b) After the Mail View
c) In the navigator after the Title Bar
(Figure 1) highlights the UI contribution made to these three “content spots”.
Figure1: Three “content spots” for Notes Mail view.
Responsibilities of “RCP Content Spot” Framework
The functionality of this framework is two fold:
1. Adding custom UI to predefined “content spots”.
2. Provide a way to define new “content spots”.
Adding custom UI to predefined “content spots”
When developers want to contribute customized UI to any of the existing “content spots”, they need to do the following:
a) Add the "com.ibm.rcp.contentSpots” dependency to the manifest.mf file, of their plugin.
Figure2: Adding Dependancy to your plugin.
b) Add the "com.ibm.rcp.contentSpots.extension” extension to their plugin.xml as described below:
<extension
point="com.ibm.rcp.contentSpots.extension">
<contentContrib
class=”<MyClassName>”
id=”<MyId>”
spot=”<SpotLocation>”
weight=> “<Some Number>”
</contentContrib>
</extension>
The “contentContrib” tag under this extension has the following important attributes:
class: The class mentioned here should extend the class “com.ibm.rcp.contentSpots. AbstractContextSpotContrib.java”. This class should implement the following methods:
/**
* createControl will render the current contribution on the parent composite
* @param parent Parent composite to render contribution
* @return Composite of the rendered contribution
*/
---- public Control createControl(Composite parent);
This method receives a composite of the parent Notes view as an input. In this method we are expected to create custom UI on top of the parent composite and return it.
/**
* Called by RCPContentSpot when the context spot should load and set
* its contained data
* @param context Map of attribute pairs
*/
---- public void load(Map context);
This method provides us a Map with various parameters. The instance of org.eclipse.ui.part.ViewPart associated with the Notes view, is amongst one of these parameters. This viewpart instance can provide useful information regarding underlying view.
/**
* Called by RCPContentSpot when the context spot should save its contained * data
* @param context Map of attribute pairs
*/
---- public void save(Map context);
This method provides the contributors an opportunity; to save the parameters from the context Map.
id: This should uniquely identify your contribution.
spot: This attribute decides the location where the custom UI will be placed.
weight: Users can have multiple UI contributions for the same “content spot”. In such a situation the contributions are displayed in ascending order of their weights. The weight string should have some number.
e.g weight="5"
Contributing UI to IBM Notes PIM views
In (Figure1) we saw that IBM Notes Mail view defined 3 “content spots”. Also, we have covered so far the details around "com.ibm.rcp.contentSpots.extension”. So we clearly understand that the 3 “content spots” defined by Notes PIM views should have a unique “spot” value.
Accordingly the list of spot names is given below:
a) After Action Bar: "com.ibm.rcp.csiviews.viewpart.CSIViewPart.afterActionBar"
b) After the Mail View: "com.ibm.rcp.csiviews.viewpart.CSIViewPart.afterViewer"
c) In the navigator after the Title Bar: "com.ibm.rcp.csiviews.viewpart.csinavviewpart.navtitlebar"
Example of contribution made after Action Bar:
Let us understand in detail the contribution made to “After Action Bar content spot”. On similar lines, UI contributions can be made to the remaining two content spots defined by Notes PIM views. The provided “com.ibm.contentspot.demo” plugin can be referred for the code.
Figure 3: UI contribution after Action Bar.
For this contribution you need to add following extension; to your plugin.xml.
Listing 1. Adding extension to plugin.xml
<extension
point="com.ibm.rcp.contentSpots.extension">
<contentContrib
class="com.ibm.contentspot.demo.pimviews.contrib.AfterActionBarView"
id="AfterActionBarView"
spot="com.ibm.rcp.csiviews.viewpart.CSIViewPart.afterActionBar"
weight="5">
</contentContrib>
</extension>
The provided “com.ibm.contentspot.demo” plugin, has a class called AfterActionBarView.java. It extends the class “com.ibm.rcp.contentSpots. AbstractContextSpotContrib.java”, implements all the required methods and contributes the user interface highlighted in (Figure 1 and 3). Also note the value of “
spot” attribute "com.ibm.rcp.csiviews.viewpart.CSIViewPart.afterActionBar", which is unique for “After Action Bar” content spot.
As you can see from (Figure 1 & 3), the custom UI contributed after Action Bar, has a button. Clicking that button will display a dialog with the part Name of underlying Notes PIM view.
This depicts that such integration will facilitate writing add-on user interfaces and application logic which is closely tied to PIM views.
Note:
(Figure 1) shows integration of custom UI for Mail view. The same extension and the same code also contributes custom UI to other PIM views of Calendar, Contacts, To Do etc.
Defining new “Content Spots”
On the line of PIM views, any Notes based Java views can leverage this framework to define their own “content spots”. As “content spots” help your Java views to become extensible hence it will be good practise to define them, right at the design stage.
To define such “content spots”, the framework takes help of the class called “com.ibm.rcp.contentSpots.RCPContentSpot.java”. For every “content spot” defined, there should be an associated instance created for RCPContentSpot.java .
The main functions of this class are:
• Give the list of all the UI contributions made to a particular “content spot”.
• Deciding the order of display of these contributions based on “weight” attribute.
To understand this let us walk through an example given below:
Figure 4: Custom Sales View with “content spot” contribution.
The provided com.ibm.contentspot.demo plugin, has the code to contribute “Sales Summary” view to IBM Notes
.
The “Sales Summary” view basically displays the number of different types of vehicles sold in a month.
Also it defines a new “content spot” so that individual departments can contribute to this view with more statistical information.
Any Notes
based Java view can define new “content spot” in six simple steps:
a) The Java view should decide the location where it wants to accept the contribution.
-- In our example, com.ibm.contentspot.demo.sales.SalesContribView.java is the place which accepts “content spot” contributions.
b) Decide a unique “spot” name.
e.g com.ibm.contentspot.demo.sales.SalesContribView.java defines the spot id as given below.
–
SALES_SPOT_ID = "com.ibm.contentspot.Sales"; //$NON-NLS-1$
For the next 4 steps please refer the code snippets pasted below. They are from com.ibm.contentspot.demo.sales.SalesContribView.java
Listing 2. Define new content spot, scan for contributions and call lifecycle method “createControl()” on each of the contributions.
private void addContentSpotContributions(Composite parent) {
_mySpot = new RCPContentSpot(SALES_SPOT_ID);
List contribs = _mySpot.getContributions();
if (contribs.size() > 0){
Iterator it = contribs.iterator();
int i = 0;
while(it.hasNext()){
IContextSpotContrib spotContrib (IContextSpotContrib)it.next();
Control c = spotContrib.createControl(parent);
}
}
}
protected void loadContentSpots() {
if(_mySpot != null) {
Map context = new HashMap();
context.put("viewPart", this);
_mySpot.load(context);
}
}
c) Instantiate RCPContentSpot.java by passing the “spot” name.
e.g. _mySpot = new RCPContentSpot(
SALES_SPOT_ID);
d) RCPContentSpot # getContributions() method will provide all the contributions made to the “spot” defined.
e.g. List contribs = _mySpot.getContributions();
e) Your Notes based Java view should invoke createControl() life cycle method on each of these contributions. This method queries each contribution made to your “content spot” and expects it to return the UI control they have created.
e.g. Control c = spotContrib.createControl(parent);
f) Optionally you can call load() and save() methods on the RCPContentSpot. This is basically used to load and save any context parameters respectively, from the parent view.
e.g. _mySpot.load(context);
Contributing to “Sales Summary” View
The provided plugin com.ibm.contentspot.salescontrib, is used by the “2 wheeler” department to contribute their UI to the “Sales Summary” view.
They use the same mechanism as discussed earlier, to contribute to a “content spot”.
Their extension defined in plugin.xml looks like this:
Listing 4. Adding extension to plugin.xml
<extension
point="com.ibm.rcp.contentSpots.extension">
<contentContrib
class="com.ibm.contentspot.salescontrib.views.TwoWheelerContribution"
id="SalesData"
spot="com.ibm.contentspot.Sales"
weight="1">
</contentContrib>
</extension>
The class “com.ibm.contentspot.salescontrib.views.TwoWheelerContribution.java” extends the class “com.ibm.rcp.contentSpots. AbstractContextSpotContrib.java” and implements all the required methods. It creates a new UI contribution with additional statistical data.
Also another thing to note is the value provided to the “spot” attribute. This value is same as “SALES_SPOT_ID” defined in the class “com.ibm.contentspot.demo.sales.SalesContribView.java”
Conclusion
The Eclipse platform helps Notes application developers to create rich user interfaces. These user interfaces become even more powerful if we have the flexibility to place them in the desired location.
This article explained in detail how the “RCP Content Spot” framework will bring in this flexibility to IBM Notes. The cited examples in the article also demonstrated, how to use this framework to hook custom UI's to Notes PIM views and the way to define new “content spots”.
.
References
• Eclipse home page
• Read the developerWorks® article, “
What is Eclipse, and how do I use it?" describes the Eclipse platform and answers some common questions.
• Read the article on the steps for “
Running Notes from the Eclipse IDE."
• Read the article on “
Using IBM Lotus Expeditor Toolkit."
• 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.