# Overview

EMF Parsley is a lightweight framework that allows easy and quick UI development based upon EMF. EMF Parsley is built on top of the EMF Edit framework and it implements features like Trees, Forms and Table builders with standard JFace databinding, providing a complete component-based toolset. EMF Parsley can be configured to use all kinds of EMF persistence implementations (XMI, Teneo, CDO) Moreover a DSL allows to easily customize several behaviors in each component.

## Parsley Components

EMF Parsley aims to provide a complete set of components to visualize your model with the introspective EMF capabilities and can be used to easily build forms, viewers or editors.

There are some components that can be used out-of-the-box and can be considered as a reference implementation of the mechanisms that are the basis of EMF Parsley itslef.

- Trees
- Forms
- Tables
- Editors
- Search boxes (coming soon)

### Customize

The main feature of EMF Parsley is that you can customize all basic UI behaviours of the components with Dependency Injection mechanisms (based on Google Guice). You can get more info in the Customizations Section, but you don't have to know all details about the internal implementation to inject your own customization because EMF Parsley provides a DSL to easy customize your UI, as explained in the next section.

#### Customize with the DSL

You can use the DSL by creating a new project with the wizard "Create a new project" -> "EMF Parsley DSL Based project"

Clicking the "Finish" button the wizard will open directly the DSL editor. You can use the content assistant to discover all features.

The DSL allows to customize the most relevant behaviors. Here we list only a few of them:

- parts lets you define your View Parts: this will correspond to the standard Eclipse extension points for the parts (see How the DSL handles the plugin.xml)
- bindings section lets you define which implementation will be used with Injection
- menu section lets you define the contextual menu for all viewers (trees and tables)
- features provider is used to retrieve the list of feature for a given EClass to build tables and forms
- viewer content provider mediates between the viewer's model and the viewer, to provide the contents to be shown
- Label Provider is used to retrieve the image and text rapresentation of the objects of a tree viewer
- Caption Provider provides captions for each feature (namely, EStructuredFeature) of the object shown in a form, in a dialog or in a table row. Different implementations can be defined for dialogs, forms and tables.
- Control Factory provides a custom implementation of the Controls for each feature shown in a form or a dialog. Different implementations can be defined forfor dialogs and forms

#### The structure of an EMF Parsley project

An EMF Parsley project, as created by the wizard, is an Eclipse plug-in project with a few additional builders.

The emfparsley-gen source folder will contain all the Java files generated by the DSL compiler. The contents of this folder should never be modified manually, since their contents will be overwritten by the DSL compiler.

The src source folder will contain an AbstractUIPlugin generated by the wizard. This is generated only during the creation of the project and it can be safely modified if you need to put other mechanisms in the activator.

IMPORTANT: it is crucial that the activator has the static method getDefault, so you must not remove that method.

If you choose one of the templates provided by the wizard, the src folder will also contain a Java class for the view, which extends the corresponding view of Parsley. This can be safely modified if you need to add some additional mechanisms or contents to the view.

You can then create additional .parsley files in the same project.

#### How the DSL handles the plugin.xml

If you specify any part in the DSL file, then the Parsley DSL will generate a plugin.xml_emfparsley_gen in the emfparsley-gen folder, in a directory named after the containing module. Then, the EMF Parsley builder will take care of merging the generated content with the plugin.xml in the root folder of the current project. If the plugin.xml does not exist it will create it. Subsequent changes to the DSL file will regenerate plugin.xml_emfparsley_gen and the builder will merge it with plugin.xml. The merging will overwrite in the plugin.xml only the elements that are specified in the DSL. Any other elements in the plugin.xml will not be touched, so you can also add other extension points manually in the plugin.xml.

This merging takes place ONLY if your project has the EMF Parsley builder nature. Since version 0.6.1 this nature is automatically applied to the projects created with our wizard. In existing projects, you have to enable the nature yourself by right-clicking on the project, then "Configure" and then "Enable EMF Parsley builder.

Note that this merging will not consider possible removed part sections in the DSL file. The merging relies on the id, so if you change the id, e.g., the viewid, in the DSL file, then you will end up with two extension points in the plugin.xml. Thus, in general, if you removed a part section from the DSL file, or if you rename an id in a part section, please make sure you manually modify the plugin.xml accordingly. The easiest way is to select to the files, and use the context menu "Compare With" => "Each Other". This way, you will soon detect the changes that have to be manually applied.

#### Obtaining the Injector

Since we also generate the plugin.xml starting from the DSL file, we already make sure that the views will be created via Google Guice injection mechanisms, using a generated executable extension factory.

If you need to obtain an injector corresponding to a specific DSL file, you can use the corresponding generated class injector provider. This is prefixed with the name of the module (first letter capitalized). For example, given this DSL module

module org.eclipse.emf.parsley.examples.firstexample {
...
}

The Java class for the injector provider will be org.eclipse.emf.parsley.examples.firstexample.FirstexampleInjectorProvider.

These injector providers have a static method getInjector() that will return the singleton injector corresponding to that module:

Injector injector = FirstexampleInjectorProvider.getInjector();

The returned injector is singleton in the sense that it is the same injector used to create instances of the view parts specified as extension points in the plugin.xml.

Obtaining the injector this way is useful, for example, when you develop a pure e4 application, where you do not define views in the plugin.xml. See Eclipse 4.x.