How to contribute to an Eclipse e4 application

Introduction

With Eclipse 3.x we learned to appreciate the usefulness of splitting up an RCP application into modules (plug-ins). Each plug-in may contribute by adding new features, e.g. user interfaces, menu items, business services, etc…
Including all, or a subset, of them allows to build in a modular way the deployed application (the procuct).

With 3.x architecture this was performed by means of Extension Point (“Extensions” tab in plugin.xml editor). With e4 this operation is made in a different way, even better, there are two ways indeed (and the third is coming …)

The first method, which is the subject of this tutorial, makes use of Model Fragment; it’s a declarative way, very similar to what was done with 3.x with plugin.xml file. Otherwise one can use a programmatic way (defining a Processor) where, by coding, it is possible to contribue or modify an application. Furthermore it is under development another approach, based on XPath.

A new plug-in with an e4 Model Fragment

In this tutorial we will see how to contribute to an e4 application with a Model Fragment. The goal we want to achieve is adding a plug-in able to contribute to the application we created in previous tutorial, with a new menu item and a view (a “part” to be exact, but we will often still call it a “view”). In particular we want to add a plug-in for managing customers (we will just add a menu item and an empty view).

Let’s create therefore a new plug-in with File New Plug-in Project, give it a name, e.g. it.rcpvision.e4training.customers), then Next. In the second wizard page we can deselect both the option for creating the Activator, and the one for creating UI contributions. Of course we will answer No to the request of creating a rich client application, since we are creating just a plug-in that will contribute to an existing application . Now skip the next wizard page (we will not use any template) clicking on Finish.

Now, instead of editing the plug-in manifest, opening files  plugin.xml/MANIFEST.MF (as we’ve get used to with 3.x platform) we will create, at the top level of this plug-in, a Model Fragment with File New Other… (or just Ctrl-N), select category e4 Model and then select New Model Fragment and press Next. The second wizard page should not require any change (the Container should already be set to current plug-in and file name should contain value “fragment.e4xmi”, which we can leave unaltered), then Finish. This file is similar to the one we saw in the previous tutorial, which defined the application EMF model (Application.e4xmi): this time however the content of this file will contain just the new model contributions. In other words it is an EMF model that extends the application model.

In order to register this file we need however to edit the plug-in manifest: let’s open therefore MANIFEST.MF file, go to “Extensions” tab, include (Add… button) the extension “org.eclipse.e4.workbench.model” (Attention: be sure that the “Show only extension points from the required plug-ins” flag be disabled!). When clicking on Finish you will be asked if the needed dependencies have to be added : answer Yes. Now, on the newly added extension right-click New fragment and modify uri attribute by pressing the nearby Browse… button and selecting file fragment.e4xmi, then OK and save.

Now go to Dependencies tab and add the following plug-in:

  • org.eclipse.e4.ui.di

  • org.eclipse.e4.core.di

  • org.eclipse.ui

  • javax.inject

so to end up with this situation:

We are now ready to add elements to the Fragment Model; we will add a Command, a Handler and a Menu item. Therefore let’s open fragment.e4xmi file, select Model Fragments node


and in the detail panel on the right side click on Add… button


three times (getting back each time to Model Fragments node) ending up this way

Adding a Command

Select the first Model Fragment element and, in the detail panel, insert the following values:

Element Id = org.eclipse.e4.ide.application
Featurename = commands


With this we are saying that this fragment will add a contribute to the application model element with id = org.eclipse.e4.ide.application (you can in fact verify that, opening Application.e4xmi file contained into application plug-in, the model root is indeed a node of type Application and with id = org.eclipse.e4.ide.application)


further we are indicating that the contribute will act on commands feature (that is the EMF attribute which corresponds to the Application commands list), see the following figure:

You may be asking why we have to input these values explicitly, instead of selecting them from a list. Indeed this is possible, with Find… buttons; if you prefer this way you should select, in the popup dialog correspondent to the first Find… button the Container-Type (in our case Application)

while in the dialog that corresponds to the second Find… button you should select commands feature, from Application entity


Anyway this behaviour will lead with the same above values into fields Element Id e Featurename.

Now we need to add the real Command: then select the first Model Fragment, in detail section choose the Command value from the combo and press Add…

on the detail set

id = it.rcpvision.e4training.customers.command.show.customers
name = Show Customers


We just defined a Command. If you developed with 3.x technology you will for sure recognize an approach which is very similar (you would have defined the Extension Point org.eclipse.ui.commands, with a “command” child node and set id and name attributes)

Adding an Handler

Let’s get to the second Model Fragment and to the Handler definition. So select the second fragment and set

Element Id = org.eclipse.e4.ide.application
Featurename = handlers


Then create, on this fragment, a Handler


set an Id for the Handler, a reference to the previously defined Command

Id = it.rcpvision.e4training.customers.handler.show.customers
Command = Show Customers – it.rcpvision.e4training.customers.command.show.customers

(you can use Find… button)

and then set a class for Handler implementation. For this you can insert the name of a class, e.g. ShowCustomerHandlers


and click on Class URI hyperlink, choose a Package (e.g. it.rcpvision.e4training.customers.handlers), a Name (e.g. ShowCustomersHandler) and Finish.

We’ll get an initial Handler implementation, that must be filled with code. For instance, for now we can just print, into execute() method, something on the console, just to be sure that the method is called.

package it.rcpvision.e4training.customers.handlers;

import org.eclipse.e4.core.di.annotations.Execute;

public class ShowCustomersHandler {
    @Execute
    public void execute() {
        System.out.println("Called ShowCustomersHandler!");
    }
}

Adding a Menu item

Now it is missing however a menu item to trigger the Command invocation. So select the third Model Fragment and this time set, as Element Id the Main Menu value in the application (in fact this is the parent to which we intend to contribute), as we can see from figure

Element Id = menu:org.eclipse.ui.main.menu

while as Featurename, with the help of Find… button, we will set children


Let’s add hence a contribute of type HandledMenuItem


setting, an Id (e.g. it.rcpvision.e4training.customers.handledmenuitem.show.customers), a Label (which will be showed on the Menu) e.g. Customers and a reference to the Command.

Adding this plug-in to the existing Product

If now we modify the product that we defined in previous plug-in (it.rcpvision.e4training.application.product) adding also the current plug-in (along with all needed dependencies)

save, get back to tab Overview of the Product and click on Launch an Eclipse Application


Let’s launch the product (checking the launch needed dependencies) and verify what we’ve done up to now

Adding a Part

In order to contribute with a Part to the PartStack of our application we first need to make sure that the PartStack has an Element Id set. So open Application.e4xmi file and set this id, e.g. to value org.eclipse.e4.ide.partstack

Now get back to fragment.e4xmi file and add another Model Fragment, setting

Element Id = org.eclipse.e4.ide.partstack
Featurename = children

Similarly to what we’ve done with the Menu item, we are acting on children list of the  PartStack element identified by the above id. In the same way in fact we add a Part

and now, like we did in previous tutorial when we added Orders part, set a Label (e.g. Customers) and a ClassURI (with a click on the hyperlink)

and fill the new view with a sample content.

    private Label label;
    private TableViewer tableViewer;

    @PostConstruct
    public void createPartControl(Composite parent) {
        parent.setLayout(new GridLayout());

        label = new Label(parent, SWT.NONE);
        label.setText("Customers");

        tableViewer = new TableViewer(parent);
        tableViewer.add("ABC");
        tableViewer.add("DEF");
        tableViewer.getTable().setLayoutData(new GridData(GridData.FILL_BOTH));
    }

Now launch and you should see this

Part options and interaction with Command

As last exercise we’ll make the just created Part closeable and we will exploit the Command tied to the Menu item to re-open the Part itself.
The first step can be obtained with Closeable option set to true