Scout/Tutorial/3.8/Modular Application

The Scout documentation has been moved to https://eclipsescout.github.io/.

Introduction

Scout applications can be built as a set of application modules extending a common core application. New modules normally consist of three additional plugins (client, shared, server). In these plugins, new functionality and GUI-components may be added to extend an existing application.

In this tutorial, a new Scout module is added to an existing Scout application. The new module provides an additional outline "Extension".

Disclaimer
The area of Scout modules and extensions is under heavy development for the upcoming Eclipse Kepler release (3.9). There will be much better support for Scout modules also in the SDK. As of now (Eclipse Juno, 3.8), there is quite some manual work involved to set-up a Scout module. This tutorial will be superceded by the corresponding tutorial for Eclipse Scout 3.9. If you are already using the Kepler M6 Release, you can already profit from the new features!

Setup

We'll start from scratch with a core Scout application and will add a Scout module to it.

Create core application

[Scout View] Create a new Scout project with name org.example.myapp and postfix core. This will create bundles with names org.example.myapp.[client|shared|server].core

Create extension bundles

[Java View] Manually create three bundles (plug-in projects) with names org.example.myapp.[client|shared|server].extension. The naming pattern is important (the postfix extension should reflect the name of your module, though).

Set-up bundle dependencies

[Java View] Open the manifest editor for all three bundles and define bundle dependencies:

org.example.myapp.client.extension depends on org.eclipse.scout.rt.client and org.example.myapp.shared.extension.

org.example.myapp.shared.extension depends on org.eclipse.scout.rt.shared. Re-export this dependency!

org.example.myapp.server.extension depends on org.eclipse.scout.rt.server and org.example.myapp.shared.extension.

Make your bundles Scout bundles

[Scout View] Use menu "Import Plugin..." on the "Scout Projects" folder and import all three extension bundles. Restart Eclipse.

Adding an Extension

Create a desktop extension

[Java View] Create a new class in the org.example.myapp.client.extension bundle: org.example.myapp.client.extension.ui.desktop.DesktopExtension which inherits from org.eclipse.scout.rt.client.ui.desktop.AbstractDesktopExtension. The class can really look as simple as the following:

package org.example.myapp.client.extension.ui.desktop;
 
import org.eclipse.scout.rt.client.ui.desktop.AbstractDesktopExtension;
 
public class DesktopExtension extends AbstractDesktopExtension {
 
}

Building the extension

[Scout View] The Scout SDK now displays three extension bundles as a separate Scout module. The orange client node also contains a "Desktop-Extension" node. You can now use the Scout SDK to build your module as you would with a normal Scout application. Well, almost. There are a few further caveats: You also need to create a separate TextProviderService for your extension module (do this in the corresponding folder in the shared bundle). Also, when adding a new outline to the desktop extension, the generated Java code does not compile. You need to fix this manually: In the constructor of the generated OutlineViewButton change Desktop.this to getCoreDesktop() and you should be fine.

Integrate with the core application

We now have a desktop extension class which we will integrate to the core application.

[Java View] Open the manifest editor for the client extension bundle. Export the package containing the desktop extension class (org.example.myapp.client.extension.ui.desktop). Open the manifest editor for the client core bundle. Import the above package from the client extension bundle.

Adapt the product files for both the client and server products. Add the extension bundles to the dependencies (client and shared bundles in the client product, server and shared in the server product).

In the Desktop class of the client core bundle, override the method injectDesktopExtensions() and add an instance of the desktop extension class to the list of extensions.

    @Override
  protected void injectDesktopExtensions(List<IDesktopExtension> desktopExtensions) {
    DesktopExtension extension = new DesktopExtension();
    extension.setCoreDesktop(this);
    desktopExtensions.add(extension);
  }

Scout SDK with a Scout module:

Simple demo with an extension outline: