Getting stared with EMF Forms

This tutorial will give a short introduction on EMF Forms and describe how to get started. If you already know EMF Forms, you can browse directly to the tutorial part.

This tutorial is based on EMF Forms versions 1.20.x and above.

Introduction

This tutorial describes a framework called EMF Forms. The purpose of the framework is to ease the development and layout definition of form-based UIs that allow browsing, creation and entry of data (CRUD). EMF Forms also includes typical features of a form-based UI such as validation and rule-based visibility of parts of the UI.

EMF Forms is a mature framework and has been applied for several industrial projects in production. EMF Forms is a subcomponent of the EMF Client Platform (ECP). However, EMF Forms is independent of ECP and can be used without it; it just integrates well into the frame of ECP.

So what is the idea behind EMF Forms?

Many business applications are data-driven and allow the user to browse, view and modify entities of an underlying data model. The entities are presented mostly in form-based layouts, whether as a desktop application, as a web application or as a mobile application.

Manual development of user interfaces for business application — even when using a visual editor — has several drawbacks. Visible components such as forms or reports are typically subject to constant change based on user feedback or changes in the data model. All changes must be done manually in the UI code. Maintenance and testing of manually coded form layouts is costly, time-consuming and error-prone. Usually forms are developed in parallel by different individuals. Therefore it can be difficult to maintain a uniform looks and feel and to enforce UI guidelines. And in the end, few developers really enjoy coding UIs manually.

The main problem is that typical UI layout technologies, such as SWT, JavaFX or Swing, are powerful but complex to use since they are designed to support a wide variety of use cases. They are not really focused on the use case of form-based business UIs.

BUT, EMF Forms provides a new way of developing form-based UIs. Instead of manually coding form-based layouts, it allows you to describe the UI with a simple model instead of with code. The model defines only concepts that are allowed by the given user interface guideline.

The goals of the approach are to:

• more efficiently produce form-based UIs

• adapt form-based UIs to changes in data models with minimum effort

• maintain or easily change a uniform look and feel

• enable a much shorter turnaround with other stakeholders (e.g., product manager, customer)

• lower the technical entry barrier to create form-based UIs

A modeled UI part is interpreted by a rendering engine, which depends on a certain UI Toolkit and translates the model into concrete concepts such as a GridLayout. EMF Forms thereby even abstracts the custom layout of the user interface from the applied UI technology and allows you to switch between the UI technology stack to Swing, SWT, JavaFX or Web – just by replacing the renderer.

The UIs produced by EMF Forms can be integrated like a manually developed UI. An obvious use case in an RCP application is the integration into a view, but even more projects use it for forms on websites, for wizards, preference pages or any other place where you display and modify data in an application.

Since EMF Forms focuses on form-based UIs, it is also a perfect match with the concept of the application model in e4. While the e4 application model describes the general design of an application down to elements such as a view, EMF Forms describes the content of these elements, i.e., what’s displayed within an Eclipse 4 view. Therefore, EMF Forms is also fully compatible with Eclipse 4 native applications.

⇒ Find out more about Developer Support and Training or contact us.

⇒ Further Documentation for EMF Forms

Tutorial

For this tutorial, we will customize the layout of the editor of the demo application of the EMF Client Platform, which is based on EMF Forms. Note that you can embed the form-based UI anywhere in your application, as a view, as part of a view or even in dialogs. The editor provided by the demo application is just a simple way to try out the features of EMF Forms. Please also note that by default, EMF Forms reflectively processes all attributes of an object, so no manual coding or code generation is needed. It is also possible to add custom controls to EMF Forms (see here) if you only want to customize the used controls.

Setup

Download Eclipse Modeling Tools Edition. Beginning with the release of Eclipse Luna SR1, EMF Forms is already part of the package Eclipse Modeling Tools. However, we recommend to update to the latest version of EMF Forms available on the EMF Forms project page (use “Update Site”). To try EMF Forms, just install the EMF Forms from the update site. However, it is possible to embed the form-based UI into a custom application without other components of ECP (see section Embedding EMF Forms in your custom application).

1. Within your Eclipse IDE, click on Help => Install New Software

2. Enter the latest update site from the EMF Forms project page into “Work with” and hit enter

3. Select EMF Forms SDK

4. Complete the wizard and restart Eclipse

Choose a domain model

For this tutorial, we will use an example model called “Make it happen!”. If you want to learn more about the example model, please see here. The example models a simple task management system including the entities “User”, “UserGroup” and “Task”. This tutorial describes how to create a simple view model for the entity User. The example model as well as the created view model are available as example bundles in your IDE. Please select New => Example and browse to the EMF Forms category. The entry “Make it happen: example model” will install the “Make it happen” example model (including the edit bundle) into your workspace. Use this option if you want to start from scratch. The entry “Make it happen: view model” will additionally create any example view model bundle. Other examples will be introduced in later parts of this tutorial.

However, you can of course also try this with your own model. Further, the tutorial is based on the demo application provided by the EMF Client Platform, including the model explorer. If you only want to use the created form-based UI, it is possible to embed EMF Forms independently of the other components of ECP. It also allows you to embed the form-based UI into any part of your application, e.g., into a view or a wizard. This is described in the section “Embedding EMF Forms in your custom application”.

Create a View Model

A view model describes the form-based UI of a certain entity type. To be available during runtime, it has to be deployed with the application. There are multiple ways to achieve this, however, the simplest one is to contain the view model in a bundle that is delivered as part of the application. The tooling of EMF Forms provides a wizard to create a new view model, as well as a corresponding bundle containing it, for an existing EMF model (.ecore file). Both options are available in the New Dialog of Eclipse. As a short-cut, you can also right-click directly on an Ecore model file (.ecore) and select EMF Forms => Create View Model Project. In the “make it happen” example, the Ecore is located here: “org.eclipse.emf.ecp.makeithappen.model/model/task.ecore”. Right click the Ecore file and choose a name for the bundle, which will contain the view model, e.g., the default: “org.eclipse.emf.ecp.makeithappen.model.viewmodel”

On the next page of the wizard, you need to select the entity of the underlying domain model (defined in the Ecore) for which we want to define the form-based UI. This will be the EClass User for this tutorial. Additionally, you can choose whether the generated view model will be already filled with default controls. In this case, EMF Forms will create a default layout showing all attributes of the entity object (User). If you wanted to start with an empty view model, uncheck this option at the bottom. For the tutorial, we will assume you start with the default layout (Checkbox selected).

Once you finish the wizard, it creates three things for you:

1. A new project containing the view model

2. A view model contained in the file viewmodels/User.view

3. A registration of that view model using the EMF Forms extension point (see the plugin.xml of the view model bundle)

The view model is automatically opened in the view model editor, which will be described in the following section.

⇒ Find out more about Developer Support and Training or contact us.

⇒ Further Documentation for EMF Forms

The View Model Editor

EMF Forms provides an editor that supports creating and modifying view models. It also allows you to preview your current layout. To open the view model editor, double click any *.view file in your workspace. The view model editor shows the current view model in a tree on the left side and the details of the selected view model element on the right side. The tree allows you to create new elements by right clicking a parent element, delete existing elements and change the hierarchy using drag and drop. The details view allows you modify the properties of an element, e.g., assigning a name. By default the wizard described in the last section creates a control for every attribute of the domain model entity (User in the example).

If you want to create controls manually, the view model editor provides a wizard for that, too. To try this, select all the generated controls (not the parent view), right click on them and delete them. Now, right click on the remaining root node (User) and select “Generate Controls”. The wizard allows you to select the attributes of the entity User that you want to create controls for. By marking “Show only unreferenced Attributes”, the dialog will only offer attributes that are not yet included in the view. Since we deleted all controls before, checking this option does not change the list in our example. Click on the “Select All” button and hit “Finish” to generate controls for all attributes again.

To control the results of the current view model, EMF Forms tooling also provides a preview. You can open it with the button located in the top right of the view model editor. This will open a second view, which presents the rendered view that is currently described in the view model editor. If you open the preview in the current state of the view model, it will display a very simple layout showing all controls in a vertical order. We will refine the layout in the next section. Now, whenever you change something in the view model editor, you can refresh the preview by clicking on the refresh button in the top right corner of the preview. Alternatively, you can turn the “auto-refresh” option on, which will refresh the preview on every change on the view model. Try to change the order of the generated controls in the view model editor using drag and drop and see how the changes are reflected in the preview.

Furthermore, to allow quick testing, the preview’s toolbar contains buttons that allow you to easily export, import or clear the data that is being displayed in the UIs fields.

The first View Model

Let’s refine the view for the entity User by creating a custom layout for the view. Basically, a layout consists of two types of layout elements. The first type is a Container, which contains other elements. A container element specifies how children are arranged. Every view model has at least one container, which is the view itself. The view is always the parent container of all other elements and, as seen before, it arranges all children elements vertically.

In this example, we will now use two additional containers, HorizontalLayout and Group. A HorizontalLayout arranges all its children horizontally. A Group (by default) arranges all its children vertically and draws a border around them. Please note that the way elements are rendered can be adapted (see here).

The second type of element is a control; it does not contain other elements. A control renders a certain attribute or reference of the domain object that is shown in the view. Additionally, there can be elements that are bound directly to an attribute or reference and show static content, e.g., a label.

Container elements can also be contained within each other. For example, to produce a classic two-column layout, you would create a HorizontalLayout with two Groups in it. The Groups contain the actual controls in this case. As the reference “Tasks” of the class User needs a little more space, we place it under the two groups.

The View Model Editor allows us to create all available elements in the tree view. To create any kind of element, right click on the parent you want to create an element in. The context menu allows all elements that can be contained in the selected parent. The root parent of any layout is the view itself. Right click on the view itself to create a HorizontalLayout. By right clicking on the HorizontalLayout, you can create two Groups. It is possible to assign names to all elements, which improves the understandability of the layout. For HorizontalLayouts, the names are for developers only with. For Groups, they will be displayed as the title of the group in the UI. Please note that you can move the control using drag and drop if you want to change the location within a layout. The model should now look something like this:

After saving the view model and the preview, the new layout will be reflected in the UI:

For this tutorial, we have only used two simple layouts. However, more complex layout elements are available in this tutorial. Additionally, it is possible and intended that you use EMF Forms to develop a custom layout that fits specific project requirements.

Embedding EMF Forms in your custom application

So far we have been declaratively defining the view model and previewing it in the view model editor. The next step is to render the view somewhere in your custom application and thereby integrate it wherever you want. EMF Forms can be embedded at any place, whether it be a window, a view, a dialog or even a wizard.

The first step in getting started with rendering is to select a UI technology. With EMF Forms you can currently choose among the following technologies:

• SWT: EMF Forms ships with an SWT renderer implementation. The preview in the view model editor in the Eclipse IDE uses this renderer also. To render your view model with SWT, please continue with the next section. The SWT renderer supports all defined view model elements and is the reference implementation. For this tutorial, we assume you chose SWT and follow the next section.

• Web-Rendering with RAP: Remote Application Platform is a technology for single-source applications for the web and the desktop. EMF Forms provides a RAP-compatible view model renderer and, therefore, forms can also be displayed in all modern browsers. The RAP renderer is also used in many projects. To bring your forms to the browser with RAP, please go to this tutorial.

• JavaFX: You can also render the same view model with JavaFX. We have developed a proof of concept for this. Please note that the JavaFX renderer is currently not activly developed and therefore not part of any release. Please get in contact with us, if you are interested in a contribution or sponsorship for a JavaFX renderer.

Please note that we have developed a number of additional and specialized renderers. For example, we are working on a web renderer based on AngularJS. If you are interested in a custom renderer or you are missing a feature supported in an existing one, we provide sponsored development for these purposes.

⇒ Find out more about Developer Support and Training or contact us.

⇒ Further Documentation for EMF Forms

Embedding EMF Forms in an SWT Application

EMF Forms provides two SWT example applications (one for 3.x and one for e4) that show how to embed form-based UIs into a view and also contain a product that shows the necessary bundles to include. Please select New => Examples => “Make it happen: eX application”. After creating the example bundle in your workspace, you can start the example application by right-clicking on the file “makeithapen_e3.product” in the root folder and selecting “Run As” => “Eclipse Application”. It shows one view displaying the dummy object in a view. It uses the view model created before.

Please have a look at the implementation of the class “View” (SamplePart for e4). The method getDummyObject() creates an example instance of the class User. The method createPartControl() renders the form-based UI with EMF Forms. EMF Forms provides API to embed the editor into any SWT view. To create a form-based UI for an EObject, you need a dependency:

org.eclipse.emf.ecp.ui.view.swt

To render an embedded view, use the ECPSWTViewRenderer found in this bundle:

ECPSWTViewRenderer.INSTANCE.render(Composite parent, EObject domainObject);

This method will pick up any registered view model and render a view for the given object on the given SWT composite. If no view model is registered, the default layout will be used.

Please make sure that the following two bundles are in your Run/Product configuration (already the case for the example application):

• org.eclipse.emf.ecp.view.model.provider.xmi: Provides the view models registered via extension point
• org.eclipse.emf.ecp.view.model.provider.generator: Provides the default layout if no view model is explicitly registered

You also need to include the necessary SWT renderers for the concepts used in your view model.

Please note that if you embed the editor, reference features will not work out of the box. This is because they require information about the context of an entity, e.g., which other entities it references. EMF Forms provides API to provide this context and also a default implementation, please see here to learn more about this.

If you need support with embedding EMF Forms into your application, if you are interested in an evaluation or you want to adapt the framework to your needs, we provide development support for these purposes.

Please visit this site to learn more about other EMF Forms features.

⇒ Find out more about Developer Support and Training or contact us.

⇒ Further Documentation for EMF Forms