Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Sirius/Tutorials/StarterTutorial

< Sirius‎ | Tutorials
Revision as of 06:37, 17 February 2014 by Frederic.madiot.gmail.com (Talk | contribs) (Test the Domain Model)

Overview

This tutorial explains how to create your first modeling workbench with Sirius.

These instructions are based on a simple Domain Model which describes basic concepts about families.

The modeling workbench created with this tutorial will allow users to visualize and edit the members of a family and their parental relationships.

Sirius 4mtuto 01.png

Create the Domain Model

A modeling workbench allows users to create or visualize models of a given Domain Model defined with EMF (Ecore model).

This tutorial relies on the basic concepts of families:

  • A family is composed of several persons.
  • Persons are men or women.
  • A person has:
    • a name,
    • a birth date,
    • one or more children,
    • two parents, a father and a mother.

Sirius 4mtuto 02.png

If your Domain Model does not exist yet, you have to create it with EMF (you can read this tutorial http://www.vogella.com/tutorials/EclipseEMF/article.html to learn how to define and generate a domain model with EMF).

In this domain model, we have defined two derived relations (father and mother). These relations are calculated using the parents relation. The generated code has to be manually modified to get and/or set these derived relations.

  • to get the father of a person, you have to find the instance of Man in the parents relation.
  • to get the mother of a person, you have to find the instance of Woman in the parents relation.

For each modified method in the code do not forget to add the tag @generated NOT.

The method codes of getFather() and getMother() are as follows:

   public Man getFather() {
       if (!getParents().isEmpty()) {
           for (Person parent : getParents()) {
               if (parent instanceof Man) {
                   return (Man) parent;
               }
           }
       }
       return father;
   }
   public Woman getMother() {
       if (!getParents().isEmpty()) {
           for (Person parent : getParents()) {
               if (parent instanceof Woman) {
                   return (Woman) parent;
               }
           }
       }
       return mother;
   }
   public void setFather(Man newFather) {
       Man oldFather = getFather();
 
       if (oldFather != newFather) {
           if (oldFather != null)
               getParents().remove(oldFather);
           if (newFather != null && !getParents().contains(newFather))
               getParents().add(newFather);
 
           father = newFather;
           if (eNotificationRequired())
               eNotify(new ENotificationImpl(this, Notification.SET, BasicfamilyPackage.PERSON__FATHER, oldFather, father));
       }
   }
   public void setMother(Woman newMother) {
       Woman oldMother = getMother();
       if (oldMother != newMother) {
           if (oldMother != null)
               getParents().remove(oldMother);
           if (newMother != null && !getParents().contains(newMother))
               getParents().add(newMother);
 
           mother = newMother;
           if (eNotificationRequired())
               eNotify(new ENotificationImpl(this, Notification.SET, BasicfamilyPackage.PERSON__MOTHER, oldMother, mother));
       }
   }


The domain model used for this tutorial can be found here : http://eclipse.org/sirius/doc/resources/getstarted/family.zip

Test the Domain Model

To test your Domain Model, you need to create a sample model containing instances of your Domain classes and relations between them.

Launch a new Eclipse Application

To launch a new eclipse application click on Run / Run Configurations and double click on Eclipse Application to get a New_configuration. You have to specify VM arguments in this new configuration as follows:

-Xms256m -Xmx1024m -XX:MaxPermSize=256m 

Sirius 4mtuto 03.png

Create a new model

In the new Eclipse runtime, select the Sirius perspective.

Sirius 4mtuto 06.png

Now you can create a new Modeling Project from the Model Explorer :


Sirius 4mtuto 04.png


Then name your sample project.

Sirius 4mtuto 05.png

The new created project is still empty, we have to create the sample model based on the defined Domain Model.

Right-click on the created modeling project and press on New / Other. Sirius 4mtuto 07.png


Then select the Basicfamily Model from the Example EMF Model Creation Wizards. Sirius 4mtuto 08.png


Select Family as the root Domain Class of your Domain Model. Sirius 4mtuto 09.png

EMF creates a model containing an instance of the root Domain Class and automatically opens a hierarchical editor.


Edit the model with the default editor

Create entities by right clicking on the root class of the sample model. Sirius 4mtuto 10.png

For each new instance, set its properties and relationships with the Properties tab. Sirius 4mtuto 11.png

Modeling workbench Initialization and Test

Let’s start creating your first modeling workbench with Sirius.

In this tutorial, we will create a modeling workbench which allows users to visualize and edit a family with its members and their relationships (father and mother).

Your sample model will be used to test this designer.

Create a Viewpoint Specification project

To create a Viewpoint Specification Project please follow the steps below:

Right-click in the Model Explorer view, Press on New, Select the Viewpoint Specification Project item.

The Viewpoint Specification Project can be created in a development workspace or in a runtime one.

In order to facilitate the test of the designer, we recommend to create the Viewpoint Specification Project in a runtime (in the same Eclipse runtime launched previously to test the domain model).


Give a name to this project.


The Viewpoint Specification Project creation wizard creates an new project containing a .odesign file. By default this file is named My.odesign, we encourage you to rename it according to your needs.


This file describes a modeling workbench which can be interpreted by the Sirius runtime.

Sirius provides a specific editor to edit this file.


Define a viewpoint

A .odesign file contains viewpoints. Each viewpoint defines a set of representations (diagrams, tables or trees).

That’s why you need to define at least one viewpoint in the .odesign file. To add a new viewpoint, right-click on the root and press New... / Viewpoint.


Do not forget to specify the Id of the added viewpoint.

The Model File Extension property defines the kind of models associated to the designer. We encourage you to set the extension associated to your domain model.




Id: The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.

Label: The label used to display this to the end-user.

Model File Extension: This field allows to associate this viewpoint to one or more semantic resource file extension(s), for several file extensions, they must be space separeted. For example to associate this viewpoint to uml and ecore metamodels, put «uml ecore».


Define a Diagram

Add a first diagram to your viewpoint by right-clicking on the created viewpoint and by selecting the menu New Representation... / Diagram Description.


A Diagram must be associated to a Domain Class: the diagram will graphically represent instances of this Domain Class.

At this step we create Persons Diagram which will display the persons of a family.




Id: The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.

Label: The label used to display this to the end-user.

Domain Class: The type of the root diagram element. For instance you may want to create an UML2 Class diagram, then the root domain class will probably be ‹Package›. On the other side if you want a Class Diagram displaying the whole model, then the root domain class is ‹Model› in UML2.

Initialisation: If set to true, the representation will be automatically created when creating a new session.

Enable Popup Bars: If true, creation tools which are visible in the palette will also be available as pop-up toolbars in the diagram itself.

Precondition Expression: The precondition is an expression preventing the creation of a diagram. If the precondition is set and the expression returns false on the root diagram element, then the diagram won’t be created.

Show on Startup: If true, existing representations of this type will be automatically opened when a session is opened.


Define a default layer

Layers allow users to show only the relevant parts of the diagram.

A diagram contains at least a default layer to display its contents.


Add a Node to the Layer

A diagram represents Nodes which are instances of the model. To create it, right-click on the layer and select the menu New Diagram Element... / Node. This will create a new node to your diagram.


All created nodes must have an Id and must be associated to a Domain class.



Id: The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.

Label: The label used to display this to the end-user.

Domain Class: The type of the root diagram element. For instance you may want to create an UML2 Class diagram, then the root domain class will probably be ‹Package›. On the other side if you want a Class Diagram displaying the whole model, then the root domain class is ‹Model› in UML2.

Semantic Candidates Expression: Restrict the list of elements to consider before creating the graphical elements. If it is not set, then all semantic models in session will be browsed and any element of the given type validating the precondition expression will cause the creation of a graphical element. If you set this attribute then only the elements returned by the expression evaluation will be considered.


The Semantic Candidates Expression property indicates how to retrieve the nodes to display on the diagram.

It can be an Acceleo 3 expression contained between [ and /] . This expression is evaluated on the object associated to the diagram (here: an instance of Family).

You can also use three interpreters dedicated to very simple expressions, by using specific tags ( feature : , service : and var:) followed by the name of the feature, service or variable.


auto-completion is available on an empty Semantic Candidates Expression property by placing the cursor in the empty field and hitting Ctrl+Space .


The completion will correspond to the empty expression for the installed query language (e.g. [/] for Acceleo 3). It will also place the cursor at the expected place where it is ready to start typing the expression.

Now, the completion proposal will correspond to the variables which are available in the expression’s context, and all the features, services, etc. which are available on the current element.


Add a Style to the Node

To define the way the node is graphically represented on the diagram, it must declare a Style. Styles can be added by right-clicking in the node and selecting the menu New Style.... Here, we have chosen a square to represent a Man.


The Style defines the graphical attributes of the Node (e.g. its color).


The Style also defines the label of the Node. By default the label is calculated with the expression feature :name

By using Acceleo 3 syntax you can enter your own expression. For example, you could display the name to upper case by specifying the Label Expression to [self.name.toUpper()/].


  • Label Format: The font formatting style to use for the label
  • Label Position: Pick either ‹node› position which mean ‹inside the node› or ‹border› to put the label around the node.
  • Hide Label By Default: Define the default visibility status of this label (available only if label position is «border»). A change of this option does not affect already existing elements.
  • Label Alignment: The alignment of the label.
  • Label Expression:
    • Expected return type: a string.
    • Available variables:
      • diagram: viewpoint.DDiagram | the current DSemanticDiagram.
      • view: viewpoint.DDiagramElement | the current view for which the label is calculated.



To test this first diagram, right-click in the Model Explorer view on the Modeling project and select the menu Viewpoint Selection.


You should see the new viewpoint persons. You must activate this viewpoint to be able to create the representations which are defined by this viewpoint.


Then right-click on the sample model and select the menu New Representation / new Persons diagram.


Give this new representation a name (e.g Persons Diagram).


When the diagram opens it displays all the instances of Man contained in the sample model. They are represented as blue squares with uppercase names as a label, as it is defined in the definition of the diagram.

Edit the Style of the Node

To improve the rendering of the diagram, it is possible to associate nodes to images. In our example, delete the square style created previously and replace it by an image style.



Specify the Workspace Path to define the image (the image can be placed in a specific folder of your project).



Workspace Path: Path for the image in the form of /myProjectID/path/to/image.png . If the image is not found in the workspace the tooling will look for it in the plugins.

Tooltip Expression: An optional expression which should return the text of the element’s tool-tip.


In the Label tab, deselect the Show icon option to avoid displaying two images for each node.




Add a second Node using the image style

Proceed the same way to create nodes for instances of Woman. Choose a different image for this node.


Saving the .odesign file immediately updates the current diagram to reflect the changes.


Add a Relation Based Edge

To display relations between Nodes, create a Relation Based Edge.


Enter the Source and Target Mappings of the relation: Sirius will select each instance of the concerned nodes which are visible on the current diagram.

Then, the designer will evaluate the Target Finder Expression on each Source Mapping to detect the corresponding Target Mapping.



Id : The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.

Source Mapping : Mapping from which the edge should start.

Target Mapping : Mapping from which the edge should end.

Target Finder Expression : Expression which should return, starting from the target element (which may be the domain class if the edge is domain based, otherwise it’s the target of the source node) the target semantic element.


Edit the Style of the Relation

Edges are initialized with a default style which defines its graphical appearance (color, line style, etc.). You can edit this style to display father relations in blue.


Then create a second edge to display mother relations in light purple.


Save the .odesign file, refresh the diagram and click on the «Arrange all» button to see the changes.


Palette Initialization

In the previous steps, we have created a modeling workbench which can display an existing model.

Let’s complete this designer with a palette containing tools to allow users to create new model elements.

Section creation

Add a new Section to the layer by right-clicking on the diagram and selecting the menu New tool... / Section.


Create Node definition

The palette is composed of tools which will allow the user to create new objects.

To create new instances of Domain Classes, add a Node Creation Description element to the Section by right-clicking on the section and selecting the menu New Element Creation... / Node Creation Description.


To define which kind of nodes will be created by the tool, the Node Creation Description element must be associated to an existing node (e.g. ManNode).



Id : The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.

Label : The label used to display this to the end-user.

Node Mappings: Node mappings you may need to create once the tool has been executed.

Precondition:

Expected return type: a boolean.

Available variables:

container: ecore.EObject | the container.




Definition of the actions performed by the Create Node tool

When the user will use the tool, actions will be executed. You have to define them.

The first step consists in adding a ChangeContext element to define the context of the actions.


The ChangeContext element contains an expression which allows Sirius to find the model element which will be the context.

To write the expression, you can use the variable container which references the object holding the current diagram (e.g. a Family instance).




Browse Expression : Expression to navigate in the model to a new element.


Then, add a Create Instance which will create a new instance of the Domain Class Man.


The Type Name property indicates the Domain Class of the instance to create.

The Reference Name property indicates the name of the relation which will be used to attach the context to the new instance.



Reference Name : Reference name in which the new instance will be stored. This reference should be part of the container element.

Type Name: Type name of the instance to create.

Variable Name : Once the instance is created, a new variable with the given name will exist binding to the newly created object.


To specify the name of the created element, you can add a Set operation.


Feature Name property contains the name of the property to set.

Value Expression property defines how to compute the value to set.



Here, the Acceleo3 expression ['man'+container.members->filter(Man)->size()/] will compute a default name depending on the number of men already created.


Feature Name : Name of the feature to set.

Value Expression : Expression returning the value to set on the current element.


Test of the Create Node tool

When you go back to the diagram which displays your sample model, you can notice that the palette contains a section and an action.

You can click on the action and move the cursor to the diagram.

The cursor will automatically change to indicate that you can click on the diagram to create a new object.


Once you have clicked on the diagram, a new Man is created and displayed on the diagram.

Its properties can be edited using the Properties view.

Back to the top