Property to Property Wiring

In Lotus Notes 8.5 and Lotus Expeditor 6.2, components in a composite application can now update other components preference values at run time, where previously they could only be set in the Composite Application Editor. In this tutorial we will create two components, a source and a target, which will be wired using exposed component properties in order to set the properties of the target component at runtime. This functionality can also be seen when using containers and landmarks, and tutorials are available in this wiki that show how to use these features.

We will be using the “PropertyBrokerListener” class to listen for property changes.

The "PropertyBrokerListener" receives a “PropertyBrokerEvent” which has several interesting attributes such as wire information, source and target component information, the property value, and the event time.

There are also several constants in the event corresponding to the event type,  for example, when actions or properties are disabled or enabled.

In this sample, we need to listen for actions being enabled and disabled, and for property value changes.

Prerequisites

Before beginning this tutorial you should be familiar with Eclipse plug-in development, and with developing components for Lotus Notes 8.5 or Lotus Expeditor 6.2.

Eclipse should also be set up to launch Lotus Notes 8.5 or Lotus Expeditor 6.2 using the Expeditor Toolkit.

We will use the following classes:

• SourceView.java
• TargetView.java

We will create a simple component that contains three combo boxes for selecting a red, green and blue value, a combo box containing all of the component's wireable properties, and a button to publish the values of the combo boxes.

1. Create a new plug-in project. In Eclipse, select File > New Project and select a plug-in project. Name the project “WireableProperties”.

2. Open the manifest file, and on the Dependencies tabs add “com.ibm.rcp.propertybroker” and “com.ibm.rcp.propertybroker.swt”.

3. On the “Extensions” tab, click Add and add “org.eclipse.ui.views”.

4. On the plugin.xml tab, add the following XML between the extension tags:  

<view name="Source View" class="views.SourceView" id="SourceView" allowMultiple="true"/>

5. Right-click on our project and select New > Class. Name the class “SourceView” and name the package “views”. This class needs to be a subclass of “ViewPart”.

6. The "SourceView" class will contain the code for publishing a value using the component preferences.

7. Download the SourceView.java file attached to this tutorial, and add the code to your SourceView class. Below are the important parts of the class.

 A selection listener is added to a button, and it calls our "publishValue" method, in order to publish our RGB property value. Our RGB value is a multi-value preference and so we separate each colour value with a ';'.
 
    public void widgetSelected(SelectionEvent e) {
       if(cboPref.getItemCount () == 0){
        return;
       }
       String name = cboPref.getItem(cboPref.getSelectionIndex());

       //get the selected property from our combo
       Property prop = (Property)cboPref.getData(name);

       //publish our RGB value, created from the combo boxes
       publishValue(prop, cboRed.getText() + ";" + cboGreen.getText() + ";" + cboBlue.getText());
    }

 

We will use the PropertyBrokerListener to update the combo box that contains our wireable properties when ever a property becomes wireable. When a property is made wireable, the PropertyBrokerlistener will call the “updatePrefCombo()” method which gets a list of properties that are wireable and populates our combo box.

    private PropertyBrokerListener pbListener = new PropertyBrokerListener() {

      public void handleEvent(PropertyBrokerEvent e) {
        if ( fullViewId.equals(e.getOwner() ) ) {

            //we need to get the type of event, to see if an actions
            //was enabled or disabled, so that we can update our list
            //of available actions
            switch ( e.getEventType() ) {
                case PropertyBrokerEvent.ACTIONS_REGISTERED:
                case PropertyBrokerEvent.ACTIONS_UNREGISTERED:
                updatePrefCombo();
                break;
            }
        }
      }
    };

The "updatePrefCombo" method will populate our combo box with all of the wireable properties. This method will be called when ever a property is made wireable, or if a property is no longer wireable.
   
    //update our combo box with the latest list of available wireable properties
    private void updatePrefCombo(){
        pb = PropertyBrokerFactory.getBroker();
        Display.getDefault().syncExec(new Runnable() {
            public void run() {
                if ( cboPref.isDisposed() ) {
                    return;
                }

                Map map = new HashMap();

                try {
                    Property[] props;
                    props = pb.getProperties(fullViewId);
                    cboPref.removeAll();

                    //get a list of all of the available properties
                    for (int i 0; i & amp;l t; ; p r o p s .le ngth; i ++) {
                        Property prop = props[i];
                        String propName = prop.getName();
                        if ( prop.getDirection() == Property.OUT ) {
                            if ( !map.containsKey(propName) ) {
                                map.put(propName, prop);
                            }
                        }
                    }

                    //get a list of all the available actions
                    Action [] actions = pb.getActions(fullViewId);
                    for (int i = 0; i < actions.length; i++) {
                        Action action = actions[i];
                        Parameter [] params = action.getParameters();
                        for (int j = 0; j < params.length; j++) {
                            Property prop = params[j].getProperty();
                            String propName = prop.getName();
                            if ( prop.getDirection() == Property.OUT ) {
                                if ( !map.containsKey(propName) ) {
                                    map.put(propName, prop);
                            }
                        }
                    }

                    //add the available actions to our combo box
                    for (Iterator it = map.keySet().iterator(); it.hasNext();) {
                        String name = (String)it.next();
                        Property prop = (Property)map.get(name);
                    &nbs p;  cboPref.add(name);
                        cboPref.setData(name, prop);
                    }

                    if ( cboPref.getItemCount() > 0 ) {
                        cboPref.select(0);
                    }
                } catch (PropertyBrokerException e) {
                    e.printStackTrace();
                }
            }
        });
    }

The "publishValue" method will simply publish a given value. We need to tell the Property Broker that a property has changed.

    private void publishValue(Property property, String value){
        pb = PropertyBrokerFactory.getBroker();
        try {
            //create a property to publish
            PropertyValue propVal = PropertyFactory.createPropertyValue(property, value);

            //inform the Property Broker
            pb.changedProperties(new PropertyValue[] { propVal }, fullViewId);
        } catch (Exception e){
            e.printStackTrace();
        }
    }

Now we just need to create our target component, which will consume the value, and use it to set its background colour.

Creating our target component

1.    First, we will need to open up our manifest file again.

2.    In the plugin.xml tab add the following xml between the tags:

<view name="Target View" class="views.TargetView" id="TargetView" allowmultiple="true"/>   

3.    The plugin xml should now look like this:

    <plugin>
               <extension point="org.eclipse.ui.views">
                  <view name="Target View" class="views.TargetView" id="TargetView" allowmultiple="true"/>
                  <view name="Source View" class="views.SourceView" id="SourceView" allowmultiple="true"/>
               </extension>
   </plugin> 

4.    Next, we need to create another view. Right click on the views package of our project and select New > class. Name the class “TargetView”. This class also needs to be a subclass of “ViewPart”.

5.    Download the TargetView.jav a fil e that i s attached to the this tutorial, and add the code to your TargetView class. Here we will go through the importa nt parts of the class.

The PropertyBorkerListener will listen for pr operty changes. When ever a pro perty value is pu blished it c all our "updat ePr ope rty Value" method.

    private PropertyBrokerListener pbListener = new PropertyBrokerListener() {
        public void handleEvent(PropertyBro kerEvent e) {
            if ( fullViewId.equals(e.getOwner()) ) {
                switch ( e.getEventType() ) {
                    case PropertyBrokerEvent.PROPERTY_VALUE_SET:
                    updatePropertyValue(e);
                    break;
                }
            }
        }
    };

   
The "updatePropertyValue" method will get the wire information from the PropertyBrokerEvent, which we will use to get the name of the property that changed. If this value is our background colour value we will update the background colour.

    private void updatePropertyValue(final PropertyBrokerEvent evt){
        Display.getDefault().syncExec(new Runnable() {
            public void run() {
                String propName = null;
                Wire wire = evt.getWire();
                if ( wire != null ) {
                    String sourceId = wire.getSourceEntityId();
                    String targetId = wire.getTargetEntityId();

                    //get the name of our property
                    if ( sourceId.equals(fullViewId) ) {
                        propName = wire.getSourceParam();
                    } else if ( targetId.equals(fullViewId) ) {
                        propName = wire.getTargetParam();
                    }
                }


                if(evt.getPropertyValue() != null){
                    if(propName == null){
                        propName = evt.getPropertyValue().getProperty().getName();
                    }   
                    //the value of our wireable property
                    String val = (Str ing)ev t.getPropertyValue().getValue();

                     //check that the property being changed is th e backgroun d colour //prope rty tha t we will create
                    if(propName.equals("bgColourTarget")){
                    String[] vals = val.split(";");
                    if(vals.length == 3){
                        for(int i =0; i < vals.length; i++){
                            colourVals[i] = Integer.parseInt(vals[i]);
                        }   
                    }
                    updateBackgroundColour();
                    }
                }
            }
        });
    }

Now that we have two components that are set up for property to property wiring we can create our application.

Creating the application

1.    Launch Lotus Notes 8.5 or Lotus Expeditor 6.2 from Eclipse and create a blank composite application.

2.    Launch the composite application editor and in the "Component Palette" select "My Palette" so that we can add our components.

3.    Right click on "My palette" and select "Add Components - Add locally installed components".  From the list in the dialog select "Source View" and "Target View" and click ok. We can now add our components to the application.

4.    Add the components, and right click the "Source View" component in the navigator and select "Edit Component Properties".

5.    In the Advanced tab add a new property called "bgColourSource", and tick the wireable box beside it. Click ok to save the changes.

6.    Now right click the "Target View" component in the navigator, and in the advanced tab add a new property called "bgCol ourTarget". Click the wireable box, and click ok to save changes.

7.    Our components are now ready to be wired together. Right click the "Source View" component in the navigator and select "Wiring".

8.    Create a wire from the "bgColourSource" property of the source view to the "Set bgColourTarget" action of the target view.

9.    Click ok to save and exit wiring. Close the composite application editor and save the changes.

10.    When our application opens if you click the publish button the background colour of the target component should change to black. If you change the values in the colour combo boxes you can change the background to any colour.

Every property that we make w ireable will s how up in the property combo box of our source view, howe ver we have only set it up to work with the target view, so that is the only property that will work, however you can have multiple properties. 

This tutorial is a very simple example of what you can do with wireable properties. The code provided in this tutorial should be a good starting point for anyone wanting to use this functionality further, and change the values of component properties at run time.