Creating a Textual Editor

The goal of this page is to create a textual editor for a chosen diagram type that you can integrate in the Cooperate Modeling Environment. The required steps include

• Definition and implementation of a grammar and a meta model
• Implementation of state calculators
• Implementation of automated issue resolutions
• Implementation of outline
• Implementation of comparator for CDO

Foundations

• Xtext
  • Textual editor framework
  • Important topics: Grammar, quickfixes, validation, outline
• EMF
  • Modeling framework for Eclipse
  • Important topics: Creating a meta model, generating code
• UML 2.5
  • Official UML standard
  • Important topics depend on the chosen diagram type, you should read this on demand

Definition of a meta model

The meta model defines the structure of the information displayed in your textual syntax. When working with Xtext, the structure of your meta model and your grammar are tigthly coupled. Therefore, it might be necessary to adjust the meta model and grammar together if you want to change anything.

First of all, you have to create a new plugin project:

• Create a plugin project that will include the meta model (it is best practice to name the project ...activity.metamodel if you create a meta model for an activity diagram)
• Create a new folder model
• Add a dependency to de.cooperateproject.modeling.textual.common.metamodel

Afterwards, you can create the meta model in the model folder:

• Set the name, ns prefix and ns uri of the root package
• For every non-artificial parser rule in your grammar, create a concrete EClass
• For every feature in your grammar, create an according EStructuralFeature
• Load the textual commons resource
  • If the textual commons meta model is installed, use the registered packages and look for http://www.cooperateproject.de/modeling/textual/commons
  • If the textual commons meta model is located in your workspace, use the workspace browser and select the ecore model
• Use the base classes of the textual commons meta model whenever possible
  • Every concrete EClass that has a counterpart in the UML meta model has to (transitively) extend the UMLReferencingElement EClass
• Add interfaces, abstract classes, and relations to improve the structure of your meta model (e.g. to introduce reasonable inheritance structures)

Next, you have to create the generator model with the same name in the model folder:

• Create a new EMF generator model from the wizard
  • Give it the file name as the ecore model
  • Choose Ecore model (CDO Native)
  • Select your newly created ecore model
  • Select the root package of your ecore model as root package
  • Select all other referenced models in the bottom area of the dialog page
• Open the generator model
  • Select the root element
    • change the Feature Delegation in the group Model to Dynamic
    • change the Model Directory in the group Model from .../src to .../src-gen
  • Select the first entry under the root element
    • set the Base Package in the group All to the name of your plugin project
• Open the generator model in a text editor
  • For all entries in the usedGenPackages attribute, replace ../../ with platform:/plugin/

Finally, you should generate the code for model, edit, and editor plugins with the generator model. You have to repeat this last step everytime you change the model.

Definition of a grammar

Before designing your grammar, please have a look at our general syntax guidelines and existing syntaxes. Additionally, you have to choose relevant elements for your diagram and omit elements that are not essential or that are rarely used.

First, you should create a new Xtext project.

• Select Xtext Project From Existing Ecore Models in the new wizard
• Select the generator model you created in the step before
• Choose your entry rule (usually you want to choose the XYDiagram element)
• Use the project name that you used for the meta model plugin but omit the .metamodel
• Use a short file extension (usually 3 digits) such as abbreviations suggested in the UML 2.5 standard Annex A
• Use the same name like the project name but append the diagram abbreviation
• Keep all settings regarding plugin generation as it is
• After pressing finish, 5 projects should have been created

In the next step, you can fix the errors in the generated grammar file:

• Replace all import statements that are marked with the platform resource URI
  • old: import "http://www.cooperateproject.de/modeling/textual/cls/Cls"
  • new: import "platform:/resource/de.cooperateproject.modeling.textual.cls.metamodel/model/cls.ecore"
• Delete all existing rules and start over

In order to generate code from your grammar file, you have to use the MWE2 workflow. Adjust the workflow in order to generate the code required for integration in the Cooperate Modeling Environment: