# 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