Tutorial - My First Sphinx Project

Introduction

This tutorial will guide you through the development of a simple application based on Sphinx. The resulting application is quite simple (1 class, 2 projects, few extension point contributions). However, thanks to the power of Sphinx, it is really functional.

Our application is a model-based application. For the purpose of this tutorial we will use the Extended Library Model Example provided by EMF.

Step 1: Getting the example meta-model

The example meta-model is provided by EMF. It consists in three generated plug-ins. Getting them is quite simple:

  1. Open menu File > New > Example... > Eclipse Modeling Framework > Extended Library Model Example;
  2. Click Next >;
  3. Click Finish to generate the three related projects, org.eclipse.emf.examples.library, org.eclipse.emf.examples.library.edit and org.eclipse.emf.examples.library.editor.

Step 2: Creating the plug-in with meta-model descriptor

The meta-model descriptor is a key-notion of Sphinx. It consists in a class identifying a meta-model to be used in the workspace. Each application based on Sphinx has to provide such a meta-model descriptor for each meta-model it uses.

Step 2.1: Creating the enclosing project

  1. Open menu File > New > Project... > Plug-In Project and click Next >;
  2. Call it org.eclipse.sphinx.examples.library.ide and click Next >;
  3. Disable option This plug-in will make contributions to the UI and click on Finish.

Step 2.2: Adding the plug-in dependencies

  1. Edit the MANIFEST.MF file in org.eclipse.sphinx.examples.library.ide/META-INF;
  2. In the Dependencies tab, add the required plug-in org.eclipse.sphinx.emf.

Step 2.3: Creating the class

  1. Select the package contained by the org.eclipse.sphinx.examples.library.ide plug-in and create an new class (right-click, then New > Class);
  2. Call it EXTLibraryMMDescriptor;
  3. Provide its superclass org.eclipse.sphinx.emf.metamodel.AbstractMetaModelDescriptor;
  4. Click on Finish.

Step 2.4: Creating the constructor

Edit the EXTLibraryMMDescriptor code to add the following default constructor:

public EXTLibraryMMDescriptor() {
    super("org.eclipse.sphinx.examples.library", EXTLibraryPackage.eNS_URI);
}

Step 2.5: Contributing to the meta-model descriptor extension point

TODO: Explain the object of this extension point.

This plug-in contributes to the meta-model descriptor provided by Sphinx.

  1. Open the META-INF/MANIFEST.MF file;
  2. Select the Extensions tab;
  3. Click Add..., uncheck option Show only extension points from the required plug-ins and select extension point org.eclipse.sphinx.emf.metaModelDescriptors; then click Finish;
  4. In org.eclipse.sphinx.emf.metaModelDescriptors add a new descriptor with the following property:
    id org.eclipse.sphinx.examples.extlibrary
    class org.eclipse.sphinx.examples.library.ide.metamodel.EXTLibraryMMDescriptor

Step 3: Creating the UI plug-in

Now we will create a second plug-in which deals with all what is related to the user interface. This plug-in does not contain any code. It only contributes to extension points of the Eclipse UI.

Step 3.1: Creating the enclosing project

  1. Open menu File > New > Project... > Plug-In Project and click Next >;
  2. Call it org.eclipse.sphinx.examples.library.ide.ui and click Next >;
  3. Enable option This plug-in will make contributions to the UI and click Finish.

Now the project exists and may contribute to extension points.

Step 3.2: Contributing to the navigator viewer

TODO: Explain the object of this extension point.

First, the UI plug-in contributes to the navigator viewer.

  1. Open the META-INF/MANIFEST.MF file;
  2. Select the Extensions tab;
  3. Click Add..., uncheck option Show only extension points from the required plug-ins and select extension point org.eclipse.ui.navigator.viewer; then click Finish;
  4. In org.eclipse.ui.navigator.viewer add a new viewerContentBinding with the following property:
    viewerId org.eclipse.sphinx.examples.explorer.views.modelExplorer
  5. In org.eclipse.sphinx.examples.explorer.views.modelExplorer add a new includes;
  6. In (includes) add a new contentExtension with the following property:
    pattern org.eclipse.sphinx.examples.library.ide.ui.navigatorContent.extendedlibrary

Step 3.3: Contributing to the navigator content

TODO: Explain the object of this extension point.

The UI plug-in contributes to the navigator content.

  1. Click Add... and select extension point org.eclipse.ui.navigator.navigatorContent; then click Finish;
  2. In org.eclipse.ui.navigator.navigatorContent add a new navigatorContent with the following properties:
    id org.eclipse.sphinx.examples.library.ide.ui.navigatorContent.extendedLibrary
    name Extended Library Content
    contentProvider org.eclipse.sphinx.emf.explorer.BasicExplorerContentProvider
    labelProvider org.eclipse.sphinx.emf.explorer.BasicExplorerLabelProvider
  3. In Library Content add a new triggerPoints;
  4. In (triggerPoints) add a new and;
  5. In (and) add a new instanceof with the following property:
    value org.eclipse.core.resources.IFile
  6. In (and) add a new test with the following properties:
    property org.eclipse.sphinx.emf.isInScope
    value true
  7. In (and) add a new test with the following properties:
    property org.eclipse.sphinx.emf.metaModelIdMatches
    value org\.eclipse\.sphinx\.examples\.extlibrary
  8. In Library Content add a new possibleChildren;
  9. In (possibleChildren) add a new and;
  10. In (and) add a new instanceof with the following property:
    value org.eclipse.emf.ecore.EObject
  11. In (and) add a new test with the following properties:
    property org.eclipse.sphinx.emf.classNameMatches
    value org\.eclipse\.emf\.examples\.extlibrary\..*
  12. In Library Content add a new dropAssistant with the following properties:
    id org.eclipse.sphinx.examples.library.ide.ui.navigatorContent.dropAssistant.extendedLibrary
    class org.eclipse.sphinx.emf.explorer.BasicDropAdapterAssistant
  13. In (possibleDropTargets) add a new instanceof with the following property:
    value org.eclipse.emf.ecore.EObject

Step 3.4: Contributing to the Eclipse editors

TODO: Explain the object of this extension point.

The UI plug-in contributes to the Eclipse editors.

  1. Click Add... and select extension point org.eclipse.ui.editors; then click Finish;
  2. In org.eclipse.ui.editors provides the following properties to the editor:
    id org.eclipse.sphinx.examples.library.ide.ui.editors.extendedLibrary
    name Extended Library Example Editor
    icon <path to a gif file used as an icon>
    extensions Library, Writer, Book
    class org.eclipse.sphinx.emf.editors.forms.BasicTransactionalFormEditor
    contributorClass org.eclipse.sphinx.emf.editors.forms.BasicTransactionalEditorActionBarContributor
  3. In Library Example Editor add a new contentTypeBinding with the following property:
    contentTypeId org.eclipse.emf.examples.library.extendedLibrary

Step 3.5: Contributing to the Eclipse property contributor

TODO: Explain the object of this extension point.

The UI plug-in contributes to the property contributor.

  1. Click Add... and select extension point org.eclipse.ui.views.properties.tabbed.propertyContributor; then click Finish;
  2. In org.eclipse.ui.views.properties.tabbed.propertyContributor provides the following properties to the propertyContributor:
    contributorId org.eclipse.sphinx.examples.library.ide.ui.editors.extendedlibrary
    labelProvider org.eclipse.sphinx.examples.common.ui.providers.AppearanceExampleTabbedPropertySheetTitleProvider
  3. In (propertyContributor) provides the following property to the propertyCategory:
    category advanced

Step 3.6: Contributing to the Eclipse property tab

TODO: Explain the object of this extension point.

The UI plug-in contributes to the property tab.

  1. Click Add... and select extension point org.eclipse.ui.views.properties.tabbed.propertyTabs; then click Finish;
  2. In org.eclipse.ui.views.properties.tabbed.propertyTabs provides the following property to the propertyTabs:
    contributorId org.eclipse.sphinx.examples.library.ide.ui.editors.extendedLibrary
  3. In (propertyTabs) provides the following properties to the propertyTab:
    label Advanced
    category advanced
    id org.eclipse.sphinx.examples.library.ide.ui.propertyTabs.advanced

Step 3.7: Contributing to the Eclipse property sections

TODO: Explain the object of this extension point.

The UI plug-in contributes to the property sections.

  1. Click Add... and select extension point org.eclipse.ui.views.properties.tabbed.propertySections; then click Finish;
  2. In org.eclipse.ui.views.properties.tabbed.propertySections provides the following property to the propertySections:
    contributorId org.eclipse.sphinx.examples.library.ide.ui.editors.extendedLibrary
  3. In (propertySections) provides the following properties to the propertySection:
    tab org.eclipse.sphinx.examples.library.ide.ui.propertyTabs.advanced
    id org.eclipse.sphinx.examples.library.ide.ui.propertySections.advanced
    class org.eclipse.sphinx.emf.ui.properties.BasicTransactionalAdvancedPropertySection
  4. In org.eclipse.sphinx.examples.library.ide.ui.propertySections.advanced add a new input with the following property:
    type java.lang.Object