Getting started 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 getting started part.

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 data entry. EMF Forms also includes typical features of a form-based UI such as validation and rule-based visibilities of certain attributes.

EMF Forms has already been applied in several industrial projects. Until now, it has always been hidden in the container project EMF Client Platform. However, EMF Forms is independent of EMF Client Platform, it just integrates well into the frame of ECP. For ECP Release 1.2, we therefore decided to give the component an explicit name: EMF Forms.

So what is the idea behind it?

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.

 allofthem 300x180 Getting started with EMF Forms

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. Additionally, there are often many forms developed in parallel that all need to comply with a uniform look and feel, and manual UI coding cannot really 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 have to support any kind of possible layout. They are not really focused on the use case of form-based business UIs.

BUT, since the release of ECP 1.2.0, 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, which 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.

image00 Getting started with EMF Forms

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. Since the 1.2 release, EMF Forms is also fully compatible with Eclipse 4 native applications.

So now you need to decide:

Do you still want to manually code UIs or do you want to have a look at our getting started tutorial?

Tutorial

For this tutorial, we will use the editor of the demo application of the EMF Client Platform, which is based on EMF Forms. Note that you can embbed 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.

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 Task. The example model as well as the created view model can be retrieved from GitHub:

http://github.com/eclipsesource/makeithappen/ (only projects in the sub-folder “core”)

The repository contains three example bundles:

  • com.eclipsesource.makeithappen.model: The example model

  • com.eclipsesource.makeithappen.model.edit: The generated edit bundle

  • com.eclipsesource.makeithappen.ui: Contains the view model

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 “Embbed the Editor”.

Setup

The first step is to get the latest version of the EMF Client Platform (including EMF Forms) available here. Please note that the features described in this tutorial are available starting from version 1.2.0, so choose this or any newer version for the installation. To try the EMF Forms, you need to install ECP into your target. If you are working in Eclipse using the default configuration, the IDE itself is your target platform . Please note that most projects use dedicated target platform, using the IDE as a target is just a simple short cut. To try the EMF Forms, the simplest way to get started is to use the other components of the EMF Client Platform, too, so just install the EMF Forms SDK including other components from ECP from the update site (into the IDE or better your target platform). However, it is possible to embed the form-based UI into a custom application without other components of ECP (see section “Embed the Editor”).

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. In the “Make it happen!” example, we use the bundle “com.eclipsesource.makeithappen.viewmodel”. Within the bundle, we create a new view model. To quickly find all models, we create a new folder “viewmodel” within the bundle. Then, we create a view model by right clicking on this folder New => File => Other. In the overview, we select EMF Client Platform => View Model.

image04 Getting started with EMF Forms

Name the new file after the entity you want to describe a view for. In this tutorial, we will describe a view for the entity Task of the “Make it happen!” example model. Therefore, we name the view model file “taskView.viewmodel”. We will describe how to modify the view model in the following section. To complete the creation of the view model, we have to register it for use by EMF Forms. Therefore, we need a dependency to the bundle “org.eclipse.emf.ecp.view.model.provider.xmi”. To register the view model, the extension point “org.eclipse.emf.ecp.view.model.provider.xmi.file” is used. Open the plugin.xml, click on extensions, add a new extension “org.eclipse.emf.ecp.view.model.provider.xmi.file”. Once the extension is created, right click on it and create a new file. The attribute filePath points to the view model file, we have just created. In the following section, we describe how to use the file we have just created to describe the layout of a view. In the example, the extension looks like this:

<extension
        point="org.eclipse.emf.ecp.view.model.provider.xmi.file">
     <file
           filePath="viewModel/taskView.viewmodel>
     </file>
</extension>

The View Model Editor

EMF Forms provides an editor that supports creating and modifying view models. It also allows you to create instances of your domain model and open them directly in the modeled UI. This allows you to preview your current layout. The view model editor needs access to your domain model, therefore, it cannot currently run in the same Eclipse instance you are using for your application development (however, we are working on enabling this based on dynamic EMF to provide a better IDE integration). To start the view model editor, you need to create a new run configuration in the workspace your domain EMF model is contained in. To create a run configuration, click on menu Run => Run Configurations. Add a new run configuration by clicking on the node “Eclipse Application”. On the first tab, assign a proper name and select to run the application “org.eclipse.emf.ecp.application.e3.application”.

image15 Getting started with EMF Forms

Select the tab “Plugin-Ins” to define, which bundles are started. Select “Launch with:” => “Features selected below”. Scroll to the feature “org.eclipse.emf.ecp.demo.e3.feature” and check it. Press on the button “Select Required” to automatically add all other required features, too.

2014 02 01 23 59 56 Run Configurations Getting started with EMF Forms

Finally, you need to add your model to this run configuration. Click on “Add Plug-Ins” (below “Select Required”) and add all models you want to use. Always add the model bundle and the corresponding *.edit bundle, too. Finally, the bundle containing the view model must also be added to the run configuration

Now, start this run configuration. The opened application (View Model Editor) should look like this:

image11 Getting started with EMF Forms

In the view model editor, we will create two projects. The first one will point to the view model file we previously created that allows us to edit the layout of a “Task” view. The second one will contain an instance of the “Make it happen!” example model. This allows us to create an instance of the domain entity “Task” to test the current layout we have modeled. The View Model Editor is combining runtime and development time features in one application. Once you deploy your view, only the editor showing instances of the domain model will be used, because users usually don’t change the layout of an application.

Create a View Model Project

This project points to the file we previously created. Select “Create new Project” from the context menu in the model explorer. Choose the “Eclipse Workspace” Provider and assign a name for the project, e.g., “TaskViewModel”. Since we have already created the view model, we select “Import existing XMI-File”. Click on “Browse File System” and navigate to the file “taskView.viewmodel”, which we created earlier. This file is located in the workspace of the IDE, the same workspace the model is located in.

Please note that “Browse Workspace” will not work, because the View Model Editor is running in a different workspace than the IDE. Please also note that we are currently working on an integration of the View Model Editor into the Eclipse IDE, which will make this manual step unnecessary.

image02 Getting started with EMF Forms

Once the project is created, you should see it in the model explorer. It currently contains an empty view:

image10 Getting started with EMF Forms

Create a Domain Instance Model Project

Before we start creating a view model, we need to create a test entity of the type “Task”. This is the entity for which we will create a layout. The entity allows us to preview the layout within the View Model Editor without starting another application. To create the entity, we use a second project, since it is not part of the view model. Therefore, we again select “Create New Project”. For convenience, we use an EMFStore project this time, because it requires zero setup.

image07 Getting started with EMF Forms

Within the domain instance project, we create an instance of type “Task”, right click on the project, select “New Modelelement” and select “Task”. The task will be opened in the editor. As we haven’t specified a view model until now, or, more precisely, the view model is still empty, the editor will use the default layout, which is to render all attributes and references in a vertical order:

image08 Getting started with EMF Forms

Now we have created a good setup to start to model the layout of a Task entity. Whenever we change the view model, we need to save it using the save button in the model explorer. Please note that an element of the project to be saved must be selected to enable the save button.

image13 Getting started with EMF Forms

After that, the editor will reflect the new layout when you re-open the task. This workflow allows us to check the result of the view model we are creating within the same application (View Model Editor). Please note that we are working on integrating this feature into the Eclipse IDE itself.

The First View Model

Once the setup is completed, we can start to create the first view model. The root element of every view model, a “View”, has already been created. As a first step, we need to assign which entity of the domain model the view model is meant for. To do that, we open the View by double clicking on the node in the model explorer.

An editor opens showing all attributes of a view. Please note that this is the same editor as the one used for the domain model instances. This might be confusing, but the EMF Forms and EMF Client Platform is so flexible that it can be used for model instances at runtime or at development time.

As a second step, we assign a name to the view. This is optional, but makes it easier to navigate a view model. Next, we assign the entity type of the view. Click on the link button on the beside the “Root EClass” label.

image05 Getting started with EMF Forms

The opened dialog shows a list of all EClasses available. It allows us to select the entity we want to create a layout for, in our case, the class “Task” from the package “task”:

image091 Getting started with EMF Forms

If we save the view model and re-open the task from the domain instance, the editor will now be empty. This shows that the editor now picks up our view model, which currently specifies an empty view. Let’s fill it again with content 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 laid out. In this tutorial, we use two different containers, “VerticalLayout” and “HorizontalLayout”. A VerticalLayout arranges all its children vertically, a HorizontalLayout arranges all its children horizontally. The second type of element is leaves and cannot contain other elements. The most important elements of this type are controls, which render 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 in each other. For example, to produce a classic two-column layout, you would create a HorizontalLayout with two VerticalLayouts in it. The VerticalLayouts contain the actual controls in this case.

image12 Getting started with EMF Forms

The View Model Editor allows us to create all available elements in the tree of the model explorer. 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 VerticalLayouts. It is possible to assign names to all elements, which improves the understandability of the layout. The model should now look like this:

image14 Getting started with EMF Forms

By now, we have created the basic layout of a two-column view. However, the layout is still empty. As a next step, we have to specify which attributes and references are rendered as controls and, even more importantly, where within the layout. Control can be created manually by right clicking on a container. For every control, you need to specify which attribute or reference it is bound to. To do this, right click on the control and create a “Feature Path Domain Model Reference”. This is a pointer to the attribute or reference from the domain model, which is displayed by the control. To chose the attribute, which should be bound to the control, click on the link button in the opened Feature Path Domain Model Reference and select the feature from the list. Please note, that you must have selected an EClass for the view before, e.g. Task.

2013 10 31 2005 Getting started with EMF Forms 2013 10 31 2010 Getting started with EMF Forms

However, it would be quite a lot of work to create all controls manually. In turn, the list of available attributes is already defined by the type of entity we created for the view model. Therefore, the View Model Editor provides support to automatically create controls for all available attributes. Right click on any container and select “Generate Controls”. The dialog allows you to select all attributes and references you want to create a control for.

image001 Getting started with EMF Forms

Please note that you can move the control using drag and drop if you want to change the location within a layout. For the example, we add four controls: name, dueDate and done in the first column and the description in the second one:

image01 Getting started with EMF Forms

After saving the view model and opening the task again, the new layout will be reflected in the UI:

image03 Getting started with EMF Forms

For this tutorial, we have only used two simple layouts. However, more complex layout elements are available or are currently under development. Additionally, it is absolutely possible and intended to develop a custom layout that fits specific project requirements. Please get in contact with us, to learn about advanced and customized layouts.

Embedding the Form-based UI into an Application

Till now, we have only used the View Model Editor to show the result of view models in the UI. The created layouts will also be available in any ECP application; see here for more details about the other components of ECP. However, you might want to only use the editor independently of any other component. Therefore, EMF Forms provides API to embed the editor into any SWT view or element, e.g., a wizard.

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, the ECPSWTViewRenderer in this bundle  is used:

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:

  • 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

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, please get in contact with us to learn more about this.

Please visit this site to learn more about other ECP features.

Share it

Twitter0
Google+7
LinkedIn
Facebook