blob: abd51a944224a6d22908b86cf21b179a0d54049f [file] [log] [blame]
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
<title>Overview</title>
<link href="book.css" rel="stylesheet" type="text/css">
<link href="code.css" rel="stylesheet" type="text/css">
<link rel="home" href="00-Main.html" title="">
</head>
<body>
<a name="Overview"></a>
<h1>Overview</h1>
<p>
<em>EMF Parsley</em> is a lightweight framework that allows easy and quick UI development based
upon EMF. <em>EMF Parsley</em> 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.
</p>
<a name="ParsleyComponents"></a>
<h2>Parsley Components</h2>
<p>
<em>EMF Parsley</em> 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.
</p>
<p>
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 <em>EMF Parsley</em> itslef.
</p>
<p>
<ul>
<li>
<em>Trees</em>
</li>
<li>
<em>Forms</em>
</li>
<li>
<em>Tables</em>
</li>
<li>
<em>Editors</em>
</li>
<li>
<em>Search boxes</em> (coming soon)
</li>
</ul>
</p>
<p>
<div class="image" >
<img src="images/01-components.png" class=" "
/>
<div class="caption">
</div>
</div>
</p>
<a name="Customize"></a>
<h3>Customize</h3>
<p>
The main feature of <em>EMF Parsley</em> is that you can customize all basic UI behaviours of the components with <em>Dependency Injection</em>
mechanisms (based on <a href="https://github.com/google/guice">Google Guice</a>).
You can get more info in the <a href="06-Customization.html#Customizations" title="Go to &quot;Customizations&quot;">Customizations Section</a>, but you don&apos;t have to know all details
about the internal implementation to inject your own customization because
<em>EMF Parsley</em> provides a DSL to easy customize your UI, as explained in the next section.
</p>
<a name="Customizations_DSL"></a>
<h4>Customize with the DSL</h4>
<p>
You can use the DSL by creating a new project with the wizard "Create a new project" -&gt; "EMF Parsley DSL Based project"
</p>
<p>
<div class="image" >
<img src="images/01-new-project-dsl-wizard.png" class=" "
/>
<div class="caption">
</div>
</div>
</p>
<p>
Clicking the "Finish" button the wizard will open directly the DSL editor. You can use the content assistant
to discover all features.
</p>
<p>
<div class="image" >
<img src="images/01-dsl-content-assistant.png" class=" "
/>
<div class="caption">
</div>
</div>
</p>
<p>
The DSL allows to customize the most relevant behaviors. Here we list only a few of them:
</p>
<p>
<ul>
<li>
<em>parts</em> lets you define your View Parts: this will correspond to the standard Eclipse extension
points for the parts (see <a href="01-Overview.html#PluginXml" title="Go to &quot;How the DSL handles the plugin.xml&quot;">How the DSL handles the plugin.xml</a>)
</li>
<li>
<em>bindings</em> section lets you define which implementation will be used with Injection
</li>
<li>
<em>menu</em> section lets you define the contextual menu for all viewers (<em>trees</em> and <em>tables</em>)
</li>
<li>
<em>features provider</em> is used to retrieve the list of feature for a given EClass to build <em>tables</em>
and <em>forms</em>
</li>
<li>
<em>viewer content provider</em> mediates between the viewer&apos;s model and the viewer, to provide the
contents to be shown
</li>
<li>
<em>Label Provider</em> is used to retrieve the image and text rapresentation of the objects of a
tree viewer
</li>
<li>
<em>Caption Provider</em> 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 <em>dialogs</em>, <em>forms</em> and <em>tables</em>.
</li>
<li>
<em>Control Factory</em> provides a custom implementation of the Controls for each feature shown in a form or a dialog.
Different implementations can be defined forfor <em>dialogs</em> and <em>forms</em>
</li>
</ul>
</p>
<a name="DslProjectStructure"></a>
<h4>The structure of an EMF Parsley project</h4>
<p>
An EMF Parsley project, as created by the wizard, is an Eclipse plug-in project with a few
additional builders.
</p>
<p>
The <em>emfparsley-gen</em> 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.
</p>
<p>
The <em>src</em> source folder will contain an <a class="jdoc" href="http://help.eclipse.org/helios/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html" title="View JavaDoc"><abbr title="org.eclipse.ui.plugin.AbstractUIPlugin" >AbstractUIPlugin</abbr></a> 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.
</p>
<p>
IMPORTANT: it is crucial that the activator has the static method <em>getDefault</em>, so you must not remove
that method.
</p>
<p>
If you choose one of the templates provided by the wizard, the <em>src</em> 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.
</p>
<p>
You can then create additional <em>.parsley</em> files in the same project.
</p>
<a name="PluginXml"></a>
<h4>How the DSL handles the plugin.xml</h4>
<p>
If you specify any <em>part</em> in the DSL file, then
the Parsley DSL will generate a <em>plugin.xml_emfparsley_gen</em> in the <em>emfparsley-gen</em> folder,
in a directory named after the containing module. Then, the <em>EMF Parsley builder</em> will take
care of merging the generated content with the <em>plugin.xml</em> in the root folder of the current project.
If the <em>plugin.xml</em> does not exist it will create it. Subsequent changes to the DSL file
will regenerate <em>plugin.xml_emfparsley_gen</em> and the builder will merge it with <em>plugin.xml</em>.
The merging will overwrite in the <em>plugin.xml</em> only the elements that are specified in the DSL.
Any other elements in the <em>plugin.xml</em> will not be touched, so you can also add other extension points
manually in the <em>plugin.xml</em>.
</p>
<p>
This merging takes place ONLY if your project has the <em>EMF Parsley builder nature</em>.
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.
</p>
<p>
Note that this merging will not consider possible removed <em>part</em> sections in the DSL file.
The merging relies on the <em>id</em>, so if you change the <em>id</em>, e.g., the <em>viewid</em>, in the DSL file, then you will end up
with two extension points in the <em>plugin.xml</em>. Thus, in general, if you removed a <em>part</em> section from
the DSL file, or if you rename an <em>id</em> in a <em>part</em> section, please make sure you manually modify
the <em>plugin.xml</em> accordingly. The easiest way is to select to the files,
and use the context menu "Compare With" =&gt; "Each Other". This way, you will soon detect the
changes that have to be manually applied.
</p>
<a name="InjectorProvider"></a>
<h4>Obtaining the Injector</h4>
<p>
Since we also generate the <em>plugin.xml</em> starting from the DSL file, we already make sure that the
views will be created via Google Guice injection mechanisms, using a generated
<em>executable extension factory</em>.
</p>
<p>
If you need to obtain an injector corresponding to a specific DSL file, you can use the
corresponding generated class <em>injector provider</em>. This is prefixed with the name of the module
(first letter capitalized). For example, given this DSL module
</p>
<p>
<div class="literallayout">
<div class="incode">
<p class="code">
<span class="keyword">module</span>&nbsp;org.eclipse.emf.parsley.examples.firstexample&nbsp;{<br/>
&nbsp;&nbsp;&nbsp;&nbsp;...<br/>
}<br/>
</p>
</div>
</div>
</p>
<p>
The Java class for the injector provider will be <em>org.eclipse.emf.parsley.examples.firstexample.FirstexampleInjectorProvider</em>.
</p>
<p>
These injector providers have a static method <em>getInjector()</em> that will return the <em>singleton</em> injector
corresponding to that module:
</p>
<p>
<div class="literallayout">
<div class="incode">
<p class="code">
Injector&nbsp;injector&nbsp;=&nbsp;FirstexampleInjectorProvider.getInjector();<br/>
</p>
</div>
</div>
</p>
<p>
The returned injector is <em>singleton</em> in the sense that it is the same injector used
to create instances of the view parts specified as extension points in the <em>plugin.xml</em>.
</p>
<p>
Obtaining the injector this way is useful, for example, when you develop a pure e4 application,
where you do not define views in the <em>plugin.xml</em>. See <a href="AdvancedFeatures.html#Eclipse4" title="Go to &quot;Eclipse 4.x&quot;">Eclipse 4.x</a>.
</p>
<p>
</p>
</body>
</html>