ShowTable of Contents
Introduction
In this tutorial, we will describe the method for adding a toolbar to configure the landmarks of your containers. This toolbar will primarily be used to add actions to the current landmark. To add the toolbar, we will be extending the LandmarkToolBar class which provides several default controls such as predefined event menu, Combo boxes for Action, Property and Selected Felds for the landmark, Add Action button and Save & Apply button to load the defined action. We will customize the SampleAppView class so that the toolbar is displayed at the top of the container and the combo boxes are pre-populated with the container specific actions, properties and fields. We will also update the SampleView class to have the text field listeners so that whenever a user double-clicks in the field, an associated filed identifier is automatically filled into the field combo box.
Following image shows the existing SampleContainer view without a toolbar.
Upon the completion of this tutorial, a toolbar will be placed at the top of the view to allow assemblers to easily add actions to the landmark pages.
Prerequisite
This tutorial will expand upon the sample described in the
Creating a Composite Application Container. You must first complete the tutorial as described in the referenced article. In order to start with developing the toolbar, you need to have the Expeditor toolkit(v6.2.1) installed and/or Expeditor Client (v6.2.1) configured as target platform into Eclipse 3.4.
Create the new toolbar
To create a new landmark configuration toolbar, we will leverage the default toolbar provided by the LandmarkToolBar class that is available in the com.ibm.rcp.composite.container.core.ui.toolbar package.
Import the required package
First lets add the package com.ibm.rcp.ca.utils.componentconfig in the MANIFEST.MF file and save it. This will be needed when we implement the IcomponentConfigurator interface in order for the toolbar to read and update the configurations of the component.
Create the new class
Let’s create a new class SampleToolBar that will extend the default com.ibm.rcp.composite.container.core.ui.toolbar.LandmarkToolBar class. We will place this class in a separate package than the rest of the other classes just for code readability perspective.
- Right click on src folder and select New --> Class. Fill out the information as shown in the image below:
- Now that you have created the new SampleToolBar class, let’s override the createControl method as shown bellow:
public Control createControl(Composite parent) {
// create a new composite that will hold the toolbar
parent = new Composite(parent, SWT.NONE);
parent.setLayout(new GridLayout(1, false));
// Get the default toolbar controls from the super class. It allows you to set appropriate Style bits depending on
// whether you would like certain controls enabled or disabled.
Control bc = super.createControl(parent, STYLE_SHOW_SUGGESTIONS);
GridData gd;
gd = new GridData();
gd.grabExcessHorizontalSpace = true;
gd.horizontalAlignment = GridData.FILL;
bc.setLayoutData(gd);
// Add the second composite to hold the SampleView's
parent = new Composite(parent, SWT.NONE);
parent.setLayout(new FillLayout());
gd = new GridData();
gd.grabExcessHorizontalSpace = true;
gd.grabExcessVerticalSpace = true;
gd.horizontalAlignment = GridData.FILL;
gd.verticalAlignment = GridData.FILL;
parent.setLayoutData(gd);
return parent;
}
The super.createControl() method allows you to add the default toolbar. The second parameter of the method allows you pass style bit. This is a way you would set which artifacts you would want displayed on the toolbar and which one you want hidden. In this case, we are indicating to show the suggestions in the toolbar. Refer to the table below for additional style bits you can use:
Style bits | Description |
|
|
Hides the Events button from the toolbar.
|
|
|
Hides the Actions drop down combo from the toolbar.
|
|
|
Hides the Properties field from the toolbar.
|
|
|
Hides the Field combo box from the toolbar.
|
Modify the SampleAppView class
- Now that you have crated the SampleToolBar class with ceateControl method let's update the SampleAppView class to have this toolbar included as part of the view. We will update the createPartControl method to have the createControl method call only when we are in the Composite Application Editor (CAE.).
@Override
public void createPartControl(Composite arg0) {
parent = arg0;
parent = createLandmarkToolBar(arg0); // add the toolbar
parent.setLayout(layout);
// Create Container Contents
createPages();
setCurrentPage("PAGE1");
}
private Composite createLandmarkToolBar (Composite parent) {
ComponentData cd = sap.getComponentData();
if (cd != null) {
// checking to see whether we are in CAE
String pref[] = cd.getPreference("com.ibm.rcp.editingApplication");
if (pref.length > 0 && pref[0].equals("true")) {
//if we are in CAE then we will add a toolbar to the view
toolbar = new SampleToolBar();
return parent = (Composite) toolbar.createControl(parent);
}
}
return parent;
}
Okay so all this code will do is place the toolbar at the top of the SampleView, but it will not have any of the combo boxes populated with component specific events, fields and properties and will not be functional. The system requires that the view class implements the IcomponentConfigurator interface in order for the toolbar to read and update the configurations of this component.
- Make the SampleAppView class implement the IcomponentConfigurator interface.
public class SampleAppView extends ViewPart implements IComponentConfigurator{
The IcomponentConfiguration interface requires only one method to be implemented. The method we need to implement is the setSaveablePropertyManager. This method will be invoked by CAE after the view is initialized and the property manager object is passed to the method. We need to make the property manager object for this component available to the toolbar so the toolbar can use the component information to pre-populate the fields in the toolbar. The toolbar will also updates property manager object upon saving the actions.
public void setSaveablePropertyManager(ISaveablePropertyManager propertyManager) {
if (toolbar != null) {
// pass this container's reference & the property manager to the LandmarkToolBar so that
// the updated prefrences can be saved back to the CAE from the toolbar
toolbar.init(sap, propertyManager);
}
}
- Now we can save the changes and test it. For now the toolbar should be functional and it will allow us to configure new actions for the landmarks PAGE1 and PAGE2.
Automatically filling the field combo box in toolbar by double-clicking on the fields in the view
With the above changes, you should be able to select the appropriate field reference using the drop-down field combo box. Wouldn't it be cool to automatically identifying the field references for appropriate text fields in the view when associating actions and properties to it? Let's make that enhancement by adding a few listeners to the Text fields of the view and then when the user double-clicks in any of the fields, its reference id will be automatically selected (filled in) in the field combo box.
To make this happen we will have to update all three classes - SampleToolBar, SampleAppView and the SampleAppPageWidget.
- Let's first add a method called registerListeners to the class we created above. Add the following method in the SampleToolBar class. This method will be called from the SampleAppView class for both of the pages when we are in CAE. It will allow us to add the MouseDoubleClick listener on its text fields. Every time user will make a double click in the text fields (FIELD_A & FIELD_B for PAGE1 and FIELD_Y & FIELD_Z for page2), our listener will get called we will extract the field reference associated with that field and set it in the toolbar.
public void registerListeners(SampleAppView view){
// We've implemented the addListenerToTextFields method in the view which will pass the
// this listener to each pages. Each page will then set the listener on every field on that page.
view.addListenerToTextFields(SWT.MouseDoubleClick, new Listener(){
@Override
public void handleEvent(Event arg0) {
// TODO Auto-generated method stub
if (arg0.type == SWT.MouseDoubleClick){
// Since we are only registered listener for the text field we can cast to Text field safely
Text text = (Text)arg0.widget;
// setField method of the super class sets the field references in the toobar
setField((String)text.getData("field"),null);
}
}});
}
- Add implementation of the addListenerToTextFields method to the SampleAppView class.
public void addListenerToTextFields(final int type, final Listener listener){
// Switch to UI Thread and call widget
Display d = Display.getDefault();
if (d != null && d.isDisposed() == false){
d.syncExec(new Runnable() {
public void run() {
if (pageMap != null ) {
Iterator<String> i = pageMap.keySet().iterator();
while(i.hasNext())
{
String key = i.next();
SampleAppPageWidget page = (SampleAppPageWidget) pageMap.get(key);
page.addListenerToAllTextFields(type, listener);
}
}
}
});
}
}
- Now lets add the final addListenerToAllTextFields method to the SampleAppPageWidget class which will add the listeners from step one to every text field on the current page.
public void addListenerToAllTextFields(int type, Listener listener){
Iterator<String> i = fieldMap.keySet().iterator();
while(i.hasNext())
{
String key = i.next();
Text text = (Text) fieldMap.get(key);
text.setData("field", key);
text.addListener(type, listener);
}
}
- Now all we have to do is make sure we call the registerListeners method in the createPartControl method of the SampleAppView class so that our listeners get registered.
public void createPartControl(Composite arg0) {
parent = arg0;
parent = createLandmarkToolBar(arg0); // add the toolbar
parent.setLayout(layout);
// Create Container Contents
createPages();
setCurrentPage("PAGE1");
if (toolbar != null)
toolbar.registerListeners(this);
}
We have only registered the listeners but we would surely need a method to unregister them as well which I have not covered in the tutorial.
Now we have our toolbar ready to be tested. Let's run it.
Test the SampleApp Container
Since our SampleAppContainer is an Eclispe based palugin, you can add into a feature update site and install it either in Lotus Expteditor 6.2.1 or Lotus Notes 8.5.1. You will need to have the Composite Application Editor feature installed as to be able to composite application.
- Open a blank composite application and then edit it using the Actions --> Edit Application menu option.
- Once CAE is opened with the blank application, you should see the SampleAppContainer in the palette of CAE. Drag & Drop the SampleAppContianer into the layout area.
- You will notice the toolbar we just added at the top of the component you just added.
- Now double click in any of the Text field, you will see the reference id of the field will be filled into the field combo of the toolbar.
- Type in a property name in the property field. Then click the "Add Action" button.
- Click on the "Save & Apply" button (Refresh) to save and apply the changes. An action should be configured for PAGE1 landmark. You can confirm it on the Lanmarks tab of the "Edit Component Properties" dialog.
Conclusion
This tutorial showed how you can add a custom landmark configuration toolbar to your container which can be displayed to the user at the top of the container. We also learned how you can easily make enhancements to assist the users by automatically filling in the fields while creating actions for the landmark.