h1. Using the Extended Editing Framework with Sirius

@Authors@ Goulwen Le Fur

{toc:style=disc|maxLevel=3}

The purpose of this *Quickstart* is to present how to integrate <a href="http://www.eclipse.org/modeling/emft/?project=eef" target="_blank">EEF</a> properties views and wizards with a Sirius diagram representation.

h2. EEF Properties views and wizards generation

The tutorial <a href="http://wiki.eclipse.org/EEF/Tutorials/First_Generation" target="_blank">EEF : First generation</a> describes the process to generate EEF properties views and wizards. Here is the main steps.

h3. Initializing and setting up EEF models

Initialize EEF generation models with the action _EEF > Initialize EEF models_ in the contextual menu of your genmodel file.

!(shadow)../images/1 - Initializing EEF models.png!

The created files use a simple strategy to define EEF properties. You can change theses settings to improve the logic of your properties. 
If you plan to use EEF properties only in a designer  (for diagrams, tables, ... but not on the EMF treeviewer), you can configure the Sirius contributor ID for the EEF views. Open the generated EEFGen model, under the root element   _Model_, select the _Gen Edition Context_   and set the value *org.eclipse.sirius.diagram.ui* to the _Descriptors contributorID_ properties.  

!(shadow)../images/2 - VP Contributor ID.png!

In order to *optimize EEF performance with Sirius*, change the root class of the generated EEF components to a dedicated Sirius aware components. This can be done by defining the value of the _Leaf Components Super Class_ to *org.eclipse.sirius.eef.components.SiriusAwarePropertiesEditingComponent*.

!(shadow)../images/2-1 - Leaf Components.png!

Another interesting properties can be changed in this model, the generation directory. Default initialization set this value to the folder _src-gen_  of the plug-in containing the EEF models.

h3. Generating EEF code

Before lauching code generation, make sure the directory pointed by this value is in the build path of the plug-in.

Add a dependency to EEF runtime *org.eclipse.emf.eef.runtime* to the plug-in where you will generate the code. 

!(shadow)../images/3 - EEF runtime dependency.png!

h2. Setting up plugin.xml file

EEF generates the java code needed for properties views and wizards. It generates also an sample _plugin.xml_ file with the extension points you have to declare.

h3. Declaring AdapterFactories and PropertiesEditionPartProviders

First part of the generated _plugin.xml_ file (@<!-- EEF Extensions -->@ ) declare @AdapterFactory@ and @PropertiesEditionPartProvider@ needed by the EEF runtime. Copy this settings without any changes to the _plugin.xml_ file of your plug-in.

!(shadow)../images/4 - Copying EEF extensions.png!

h3. Declaring properties sheets

Second part of the generated _plugin.xml_  file (@<!-- Tabbed properties views extension -->@) has extensions for tabbed properties sheets. 

There is two options at this moment :

* if you have set the Sirius contributor idea during the EEF models initialization step, all you have to do is to copy the second part of the generated _plugin.xml_  file in your plugin.xml file
* if you haven't set the Sirius contributor idea, you might want to use the EEF properties in several contexts. In this case, you have to duplicate the second part settings for each context (i.e. for each contributor ID you want to contribute EEF properties). And for each contributor ID you have to change the contributor ID field for each extension point :

bc..    

  <extension
         point="org.eclipse.ui.views.properties.tabbed.propertySections">
      <propertySections
            contributorId="org.eclipse.sirius.diagram.ui">
         <propertySection
               class="org.eclipse.emf.samples.conference.parts.forms.ConferencePropertiesEditionPartForm"
               filter="org.eclipse.emf.samples.conference.providers.ConferencePropertiesEditionProvider$EditionFilter"
               id="org.eclipse.emf.samples.conference.section.Conference"
               tab="Base">
         </propertySection>
pre. 
						...

bc..          
      </propertySections>
   </extension>

p. 

Note: this configuration can also be cloned to be used with Sirius tables and trees (by using the following property contributor ids 
@org.eclipse.sirius.table.ui.EditorID@ and @org.eclipse.sirius.tree.ui.EditorID@).

A @propertySection@ must be declared for each *tab* generated in the  @org.eclipse.ui.views.properties.tabbed.propertyTabs@ extension.

Note: if you have not set *Descriptors Contributor ID* in the @.eefgen@ model and you override the @org.eclipse.sirius.diagram.ui@, @org.eclipse.sirius.table.ui.EditorID@ or @org.eclipse.sirius.tree.ui.EditorID@ contributorId, do not forget to remove the use of @org.eclipse.emf.eef.runtime.ui.utils.EEFLabelProvider@ as labelProvider. Otherwise you will get a Sirius type name as title of the properties view instead of the type name of the semantic model element.

h2. Testing properties view

After this settings, the generated properties views must be available from a Sirius diagram. You can run an eclipse application to test it.

!(shadow)../images/5 - Properties view testing.png!

h2. Optional tasks (tabs optimization)

h3. Moving EEF property sheet tabs on top

By default, the EEF property sheets tab appear at last in the properties tabs.

It is possible to move them to make them appear at the top of the tab list :

!(shadow)../images/6 - Property sheet on top.png! 

To do this, you have to modify the @org.eclipse.ui.views.properties.tabbed.propertyTabs@ section by changing the property category of your tabs. Instead of using the ones that have been created in the current @plugin.xml@ (through the @org.eclipse.ui.views.properties.tabbed.propertyContributor@ extension point), it is possible to use the ones defined by Sirius :

* @semantic & extension@
* @semantic@
* @extension@
* @behaviors@
* ...
(please refer to the @plugin.xml@ file of @org.eclipse.sirius.diagram.ui@ for a complete list).

Example :

bc.. 
   <extension
         point="org.eclipse.ui.views.properties.tabbed.propertyTabs">
      <propertyTabs
            contributorId="org.eclipse.sirius.diagram.ui">
         <propertyTab
               label="Base"
               category="semantic &amp; extension"
               id="Base">
         </propertyTab>
      </propertyTabs>
   </extension>

p. 

It is also possible to use the @afterTab@ property to manage precisely the position of the EEF tabs (to put a tab before the first tab, use the value @top@).

Example :

bc.. 
   <extension
         point="org.eclipse.ui.views.properties.tabbed.propertyTabs">
      <propertyTabs
            contributorId="org.eclipse.sirius.diagram.ui">
         <propertyTab
               afterTab="top"
               label="Base"
               category="semantic"
               id="Base">
         </propertyTab>
      </propertyTabs>
   </extension>

p. 

h3. Multiple tabs 

Several conditions have to be met in order to get several tabs for a given semantic @EClass@ :

# First of all, *one view must exist* in the @View Repository@ of the @fs.components@ file *for each tab that has to be shown* for the given semantic @EClass@
# The @Properties Edition Component@ associated to the semantic @Eclass@ must reference these views
# In the @plugin.xml@ file :
## One @propertyTab@ XML node must exist for each expected tab (@org.eclipse.ui.views.properties.tabbed.propertyTabs@ extension point). The @id@ must match the view names in the EEF @components@ file.
## One @propertySection@ XML node must exist for each expected tab(@org.eclipse.ui.views.properties.tabbed.propertySections@ extension point), the @tab@ attribute referencing the tabs defined in the @propertyTabs@ section.

To illustrate it, let's imagine that we have a semantic model that describes a filesystem in which we want to get two tabs (@File Basic@ and @File Advanced@) for the semantic @File@ @EClass@.

Let's consider that we also have an @components@ file containing (at least) :

# A view named @File Basic@
# A view named @File Advanced@
# A @Properties Edition Component@ binded to the semantic @File@ @Eclass@ and referencing both @File Basic@ and @File Advanced@ views

In the @plugin.xml@ file, the tabs declaration should appear like this (notice that in this sample we use Sirius categories in order to make our tabs appear at first as described in the previous paragraph, which is not mandatory) :

bc.. 
<extension point="org.eclipse.ui.views.properties.tabbed.propertyTabs">
   <propertyTabs contributorId="org.eclipse.sirius.diagram.ui">
      <!-- 
          Other declarations : Base, ... 
        -->
      <propertyTab
            label="File Advanced"
            category="semantic &amp; extension"
            id="File Advanced">
      </propertyTab>
      <propertyTab
            label="File Basic"
            category="semantic &amp; extension"
            id="File Basic">
      </propertyTab>
   </propertyTabs>
</extension>
p. 

And the property sections declaration should appear like this :

bc.. 
<extension point="org.eclipse.ui.views.properties.tabbed.propertySections">
   <propertySections contributorId="org.eclipse.sirius.diagram.ui">
      <!-- 
          Other declarations : Base, ... 
        -->
      <propertySection
            class="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
            filter="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
            id="fileAdvanced"
            tab="File Advanced">
      </propertySection>
      <propertySection
            class="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
            filter="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
            id="fileBasic"
            tab="File Basic">
      </propertySection>
   </propertySections>
</extension>
p. 

Here is the result :

!(shadow)../images/7 - Multiple tabs.png!

h3. Programmatically hide and show EEF property sheet tabs

It is possible to hide and show EEF tabbed property sheet tabs by providing a filter to the property sections (@org.eclipse.jface.viewers.IFilter@).

The most simple way to do this is to create a class that extends @org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection@ (this class brings a utility method (@resolveSemanticObject@)) that helps to retrieve the semantic object that is targeted by a Sirius UI part).

Example #1 (based on a test of the semantic object) : 

bc.. 
public class SemanticBasedPropertySectionFilter extends PropertiesEditionSection {

    @Override
    public boolean select(Object toTest) {
        EObject semanticObject = resolveSemanticObject(toTest);
        if (semanticObject instanceof MySemanticEClass) {
            boolean mustBeShown = true;
            // Code here the conditional tests...
            return mustBeShown;
        }
        return false;
    }

}
p. 

Example #2 (based on a test of the Sirius diagram identifier) :

bc.. 
public class SiriusIdBasedPropertySectionFilter extends IFilter {

    @Override
    public boolean select(Object toTest) {
        EditPart editPart = (EditPart) toTest;
        View view = (View) editPart.getModel();
        Diagram diagram = view.getDiagram();
        EObject element = diagram.getElement();
        String diagramId = ((DDiagram) element).getDescription().getName();
        return "<my diagram id>".equals(diagId);
    }

}
p. 

The filter has to be referenced from the @plugin.xml@ file in the *@filter@* attribute of the corresponding @propertySection@ :

bc.. 
<propertySection
       class="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
       filter="org.mypackage.MyPropertySectionFilter"
       id="fileBasic"
       tab="File Basic">
</propertySection>
p. 

h3. Hide Sirius built-in property sheet sections (and the corresponding tabs)

The current plugin (@org.eclipse.sirius.eef.adapters@) provides an extension mechanism that allows one to hide several Sirius built-in sections (and the corresponding tabs).

To be used, as a pre-requisite, a property section contributor must be defined (org.eclipse.ui.views.properties.tabbed.propertyContributor extension point) with the following section descriptor provider (@org.eclipse.sirius.eef.section.SiriusFilteringSectionDescriptor@):

bc.. 
<extension point="org.eclipse.ui.views.properties.tabbed.propertyContributor">
   <propertyContributor 
      contributorId="org.eclipse.sirius.table.ui.EditorID"
      sectionDescriptorProvider="org.eclipse.sirius.eef.section.SiriusFilteringSectionDescriptor">
    ...
   </propertyContributor>
</extension>
p. 

At this point, it is possible to declare which section have to be hidden for which contributor id. The following example shows how to hide the Semantic section from the Sirius diagrams property sheet and the Core and Semantic sections from the Sirius table property sheet :

bc.. 
<extension
      point="org.eclipse.sirius.eef.adapters.sectionFilters">
   <propertyContributorFilters
         contributorId="org.eclipse.sirius.diagram.ui">
      <sectionFilter
            id="property.section.semantic">
      </sectionFilter>
   </propertyContributorFilters>
   <propertyContributorFilters
         contributorId="org.eclipse.sirius.table.ui.EditorID">
      <sectionFilter
            id="org.eclipse.sirius.table.ui.section.core">
      </sectionFilter>
      <sectionFilter
            id="org.eclipse.sirius.table.ui.section.semantic">
      </sectionFilter>
   </propertyContributorFilters>
</extension>
p. 

h2. Opening EEF wizard on a double click

An external java call is available to open a EEF Wizard editing the current selected element. This action can be used for the double click. In a tool section, create a _Double Click Descriptor_ and name it *Open EEF Wizard*. The _operation_ of this element is only an _External Java Call_. Name it *Open EEF Wizard Action* and define the _id_ *org.eclipse.sirius.eef.actions.openPropertiesWizard*.

Finally, make a reference to this descriptor from each mapping you want to have a EEF Wizard on double click.

!(shadow)../images/8 - Double click descriptor.png!

A double click on the selected mapping must open a EEF Wizard

!(shadow)../images/9 - EEF Wizard on VP.png!


        