How to implement a new property view in WSO2 Integration Studio — Developer’s guide
By: Heshitha Hettihewa
Tags: Wso2 Ei, Developer Studio, Esb, Integration, Wso2

The latest release of WSO2 Integration Studio is packed with a whole new look in its properties pane. Instead of the existing table based property editor now we are using an html form like property editor where we have more control over the UI elements so we can make the whole experience more appealing to the developer. The magic behind this comes with a new framework we have used known as EEF[1]. This blog describes how to make use of the framework and important constructs of the Integration Studio properties view.

Existing Properties Pane

New Properties Pane

In the existing table based property view there were many limitations we had to face. The main blocker was In user experience (UX) aspect, UX describes that there are input field types which match the most based on the behavior of the property. But the input types are very limited if we use table-based property view. So there is a certain limited level where we can go with the table based approach.

That’s why we’ve decided to migrate all the property views to new form-based approach supported by the EEF, where we can make it more UX friendly.

Architectural Changes

Existing property pane is made of a SWT Table[2] handled by TabbedPropertySheet[3] implementation. So basically it’s a 2 column table which holds the properties as key-value pairs. Property key in the first column and property value in the second column. These key-value pairs are provided by various ItemProvider(ex:- [4]) classes. So there is a one table element visible at all times and the items(Property items) provided are changed when we click on the mediator diagram element.

This architecture is changed completely in the new EEF property view. In this implementation, we have forms[5] for each mediator element instead of the table widget. These forms are SWT forms which have a createControls method as usual (Eclipse forms API[6]). This form has the UI element definitions. The implementation of this form provides us with more control than the table viewer. We can use any SWT form element(Radio button, text inputs, text areas, combo boxes, etc…) here and design the form the way we need. It provides the full design potential that SWT forms have. These SWT forms are contributed to the workbench using plugin.xml(See property section contributions in [7].).

Implementation

The main data model we use in ESB tooling is ECore, provided by EMF framework. It holds all the data we persist in ESB diagram and property views. All the diagram and property implementations are either updating this model or change listening to the model and act accordingly. EEF framework also utilizes this ECore model. But without directly interacting with the ECore model it generates a new UI config layer(esb.components[8]). This config provides a UI based mapping to the Form elements and ecore model elements. If you’ve already installed EEF 1.5(This is listed under modeling updates of oxygen update site) you can right click on the ecore model and generate it[9].

You can see the mapping below. In the repository node, you can see the view (A property form). Inside that, we have containers which map to sections in property form. These containers can be used to organize the properties. Inside the containers, we have the actual property elements. Which we can map to any SWT widget accordingly. When you are done with defining the UI elements you can move to properties edition context definition.

EEF components file

The properties edition context node maps the defined view to model element. If you expand the property node you can see for every properties edition component there is the set of property elements which you can map to the view and the ecore model.

Properties Edition Context

P.S — Complex elements or custom property elements other than the primitive element types(String or numbers) are not mapped automatically. So we have to create new view elements and properties edition elements manually and map it to the ecore element.

After you are done with configs you can generate the classes out of the config by following this[9].

For each mediator element there are 4 important classes. Those are

PropertiesEditionPart

This is the interface where main UI classes are implemented. This has setter and getter methods of each of the property elements.

PropertiesEditionPartForm

This class is the actual implementation of the UI form. This is an extended version(EEF specific) of a SWT form. The entry point of this class too is the createFigure method(Just like CreatePartControls method in SWT Form). In createFigure we have a form and inside that we call createControls method which will fill the UI elements of each property. If you take a look at the create controls method you can see we have used an EEF specific traversal method through the property elements.

createControls Method

In EEF we have a properties composer(PartComposer) which will iterate through a given composition sequence and create the properties elements(By calling the createUI methods accordingly) in the given step order of the sequence. So it will be visible in the UI form in the given sequence.

Log mediator properties elements

You can see in each of the steps, the composer calls a method which returns a SWT composite widget which will be added to the main form. Ex :- CreateLogSeperatorText()[14]. Inside these methods, we are building a SWT composite which contains a property label(Ex : — Log Seperator) , UI element (Ex :- a text box widget) and a placeholder for help content. Along with these we have the listener events for UI elements(Focus listeners and key listeners) also configured in this method. In these listener events, we have the code for ecore model updates. So we are contributing this fully configured composite to the composer and it injects this composite accordingly to the parent form.

In EEF implementation it uses an EEF specific id to identify each of the property elements. These IDs are located in [18]. These ids are used to identify UI elements when creating part controls, updating model etc…

The above implementation creates the UI elements initially but there are cases that we have to hide or show elements conditionally (Ex :- if we selected Log mediator value type to expression, we should hide the value text field) These type of validations are done by validate[15] method in each of the classes. This method is called in the refresh method in each of the classes so it will redraw the form without the hidden fields.

In this implementation, we can configure a help content for each of the property elements. The contents of each of the elements are externalized to this property file[16] so anyone can add or change help content without going through the code. The help content key convention is

esb-{MediatorName}Mediator-{UI Container}-{Property Name}

Ex :- esb-LogMediator-properties-logCategory

PropertiesEditionPartImpl

Impl class is mostly the same as the form class. Same methods exist in impl class too. The main difference is it contributes to dialog boxes instead of the form in the property pane. In ecore model there are some elements such as LogProperty[17] which has no form view in property pane instead it only has a dialog box view. The UI view of this element is only visible when you click on a form’s property element as a dialog box. As an example, Log property’s UI view is visible only when you click on Log properties field in Log mediator property form. So these Impl classes denote these elements which have a dialog box view. And the same UI validation and contribution logic as forms apply to these impl classes also.

PropertiesEditionComponent

This class bridges the data related gap between UI view (Forms and Impls) and ecore model. Methods in this class are used to fill the values to property elements from ecore and vice versa. There are 2 important methods.

InitPart — This fills the property values initially. This method takes persisted values from ecore model and calls the setter and getter methods of PropertiesEditionform/PropertiesEditionimpl class. This method runs once we click on a mediator in the diagram (After the createFigure method in PropertiesEditionform/PropertiesEditionimpl class.). Having said that this method retrieves values from ecore model it specifically fetches a ecore impl object related to the clicked mediator in the diagram (Ex:- if you click on log mediator object it fetches LogMediatorImpl object). (PS — Don’t get confused with the PropertiesEditionImpl and MediatorImpl, PropertiesEditionImpl is a UI element class from EEF framework usually resides in gmf.esb.edit plugin while MediatorImpl class creates ecore data model object from EMF and the class usually located in gmf.esb plugin).

updateSemanticModel — This method is used to update the ecore model (Specifically MediatorImpl object) from the data of UI elements in the PropertiesEditionform/PropertiesEditionimpl object. If you input some new value it gets updated in the model through this method.

I hope the above details will be helpful to understand the new properties view implementation.

Cheers.

[1]. https://www.eclipse.org/eef/#/

[2]. https://www.vogella.com/tutorials/SWT/article.html#formlayout

[3]. https://www.eclipse.org/articles/Article-Tabbed-Properties/tabbed_properties_view.html

[4]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src/org/wso2/developerstudio/eclipse/gmf/esb/provider/LogMediatorItemProvider.java

[5]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/forms/LogMediatorPropertiesEditionPartForm.java

[6]. https://www.vogella.com/tutorials/EclipseForms/article.html

[7]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/plugin.xml

[8]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/model/esb.components

[9]. https://wiki.eclipse.org/EEF/Tutorials/First_Generation

[10]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/LogMediatorPropertiesEditionPart.java

[11].https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/forms/LogMediatorPropertiesEditionPartForm.java

[12].https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/impl/LogMediatorPropertiesEditionPartImpl.java

[13]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/components/LogMediatorPropertiesEditionComponent.java

[14]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/forms/LogMediatorPropertiesEditionPartForm.java

[15]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/forms/PropertyMediatorPropertiesEditionPartForm.java

[16]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/presentation/helpcontent.properties

[17]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/forms/LogPropertyPropertiesEditionPartForm.java

[18]. https://github.com/wso2/devstudio-tooling-esb/blob/master/plugins/org.wso2.developerstudio.eclipse.gmf.esb.edit/src-gen/org/wso2/developerstudio/eclipse/gmf/esb/parts/EsbViewsRepository.java