Getting Started

To get started, you may download "Eclipse Modeling Tools" or "Eclipse IDE for Java and DSL Developers" from Eclipse Downloads.

This will ensure you have EMF and related Tools installed and ready to go (you may as well use any other Eclipse package, provided that you have installed also EMF and its tools).

Top

Installation

Now select "Help" -> "Install New Software..." and in the "Work with:" field insert the EMF Parsley update site http://download.eclipse.org/emf-parsley/updates and install all features. Although sources are not strictly required, it might help when using EMF Parsley to have a look at its sources.

Top

First Example

The purpose of this first example is to make use of the classical EMF Library Model example and create a view for editing such models using an EMF Parsley enabled plug-in.

So let's start by creating the model plug-in with

  1. File -> New... -> Example...
  2. from Category "Eclipse Modeling Framework", select "Extended Library Model Example"
  3. press Next and Finish

You will end up with three plug-ins:

  • org.eclipse.emf.examples.library (the model plug-in)
  • org.eclipse.emf.examples.library.edit (the edit plug-in)
  • org.eclipse.emf.examples.library.editor (the editor plug-in)

Please consider that here we are starting from this well known EMF model taken out-of-the-box from Eclipse, but you can start from your EMF model (in that case you may probably omit the ".edit" and ".editor" plugins, depending on your model).

Now you can create your first example with the appropriate wizard.

  1. select "File" -> "New" -> "Project..."
  2. from the "Emf Parsley" category select "Emf Parsley Dsl based Project"
  3. click "Next"
  4. give a name to the project (e.g. "org.eclipse.emf.parsley.examples.firstexample")
  5. click "Finish"
The generated project has some classes and a module.parlsey file, which opens automatically. Just type the following content into the {} block (note that context assist is available)

parts {
    viewpart org.eclipse.emf.parsley.examples.firstexample.view.library.treeform {
        viewname "My Library Tree Form"
        viewclass 
    }
}

Here above we have just declared a view part with

  1. id "org.eclipse.emf.parsley.examples.firstexample.view.library.treeform"
  2. name "Library Tree Form"
  3. class: not yet set, we are going to create "org.eclipse.emf.parsley.examples.firstexample.views.LibraryTreeFormView"

So there is still an error, in fact we need to create the declared class. Suggestion: Just copy the above qualified class name ("org.eclipse.emf.parsley.examples.firstexample.views.LibraryTreeFormView"), select the project, right-click and select File -> New -> Class. Now paste the clipboard content into "Name:" field: the package and class name will be automatically splitted into right fields. Then click "Finish".

Now modify the view class code with this content:

import org.eclipse.emf.parsley.views.AbstractSaveableTreeFormView;
import org.eclipse.emf.common.util.URI;

public class LibraryTreeFormView extends AbstractSaveableTreeFormView {

    protected URI createResourceURI() {
        return URI.createFileURI( System.getProperty("user.home") + "/MyLibrary.library" );
    }

}

Now get back to module.parlsey file, go just after "viewclass" keyword, type "LibraryTreeFormView" and Ctrl-Space: the content assist will set automatically the correct qualified name

viewclass org.eclipse.emf.parsley.examples.firstexample.views.LibraryTreeFormView

when you save the above file you will notice that a new file ("plugin.xml_emfparsley_gen") is generated into the root folder of your project. Just copy this file into "plugin.xml".

Let's focus briefly on the above createResourceURI() method: our goal is allowing to manage a library model instance which persists on a EMF Resource. In this example we choose to use the EMF default persistence (XMI), but you can provide any URI (e.g. using Teneo, CDO or any other EMF Resource Persistence implementation) In particular here we choose to persist the Resource in a XMI file named "MyLibrary.library" into the user home folder (you might want to change it with any other path).

We need a Dependency from the model plug-in: so open MANIFEST.MF file, go to Dependencies tab, press "Add..." button in "Required Plug-ins" section and insert "org.eclipse.emf.examples.library" among dependencies.

Before executing this code we need to do some little more work in order to initialize the Resource.

An easy way to overcome this issue can be the following:

  1. open the class *GuiceModule (FirstexampleGuiceModule in this example) that the wizard created for you. Note that this is a key class for all customizations; it allows to override several methods in order to provide custom behaviors and implementations.
  2. override method bindEmptyResourceInitializer() providing a class for Resource initialization

    public Class<? extends EmptyResourceInitializer> bindEmptyResourceInitializer() {
        return LibraryEmptyResourceInitializer.class;
    }

  3. create a new class LibraryEmptyResourceInitializer extending from EmptyResourceInitializer for Resource initialization

    import org.eclipse.emf.parsley.resource.EmptyResourceInitializer;
    import org.eclipse.emf.ecore.resource.Resource;
    import org.eclipse.emf.examples.extlibrary.EXTLibraryFactory;
    import org.eclipse.emf.examples.extlibrary.Library;

    public class LibraryEmptyResourceInitializer  extends EmptyResourceInitializer { 
        
       public void initialize(Resource resource) { 
           super.initialize(resource); 
           Library library = EXTLibraryFactory.eINSTANCE.createLibrary(); 
           resource.getContents().add(library); 
       } 

    }

    The method initialize() will be executed only when the Resource is empty (i.e., it has no contents).

now get back to the MANIFEST.MF and run the example

As an Eclipse RCP developer you know, of course, that this will start another Eclipse instance (unless you add an Application plug-in to the launch or define an Application in the current plug-in).

In this second Eclipse instance you can show the View in this way:

  1. Window -> Show View -> Other...
  2. from Category "Other", select "My Library Tree Form"
  3. press OK

With this simple view you can start editing the model instance. For example you can set the "name" field; as soon as you start typing characters into this field you will notice that:

  1. the View turns to a "dirty" state (an asterisk symbol appears on the view tab)
  2. the "Save" toolbar button is enabled
  3. the typed characters are reflected into the label correspondent to the Library icon

if you now perform a "Save" action the persistence mechanism will trigger and you will see that file <user.home>/MyLibrary.library is being created on the file system. From now on, this file will keep the state of the model object whenever you change and save it.

To create a Writer into the Library just right-click on the Library object and select New Child -> Writer

Please note that you might see a slightly different content in the above context-menu in case you deleted the .edit plugin when creating the model (e.g. "Writers Writer" instead of "Writer", "Stock Book" instead of "Book" and similar (this is because with EMF it is possible to customize labels also via .edit plugin).

Now set for instance the writer "name" field and save. Now just play around creating Books, associating them to Writers and so on. As you can see you can entirely manage the EMF model instance: creating, modifying and deleting elements.

Whenever the current selection on the upper side of the view changes, then the lower side shows the detail of this selection.

However, up to this point, you have no control over the field to be shown and its order; for example you may want just the "name" attribute for the Library and "name", "address" and "books" attributes for Writers and maybe "title", "authors" and "category" for Books.

Well, it's indeed very easy to obtain this: just edit the module.parsley file, adding the following import (without ending line with ";")

import org.eclipse.emf.examples.extlibrary.*

and then defining the features to show

module ... {

    parts { 
        ...    
    }
    
    featuresProvider {
        features {
            Library -> name
            Writer -> name, address, books
            Book -> author, title, category
        }
    }
}

Remeber that code completion is available, just exploit it since it helps a lot.

If you restart now the application you will see that, when selecting an object, only the declared attributes will be shown. Furthermore, they are shown in the specified order.

Did you run the application in Debug mode? Well, then you can change fields and order, save and see the changes without even restarting the application.

Do you want to change text used for attribute labels in the detail? Just add the following:

propertyDescriptionProvider {
    text {
        Book : author -> 'Wrote by:'
        Writer : name -> 'Name:'
    }
}

Or do you want to change the label shown on the tree nodes on the upper side and as detail title? Maybe want to format the book label like this?

labelProvider {
    text {
        Book b -> '"' + b.title + '"' +' (by '+ b.author.name + ')'
    }
}

Top

RCP Mail Example