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

Difference between revisions of "Sirius/Tutorials/StarterTutorial"

(Define the actions performed by the Create Node tool)
 
(55 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Category:Sirius]]
 
=Overview=
 
=Overview=
  
This tutorial explains how to create your first modeling workbench with Sirius.  
+
This tutorial explains how to create your first modeling workbench with [http://www.eclipse.org/sirius Eclipse Sirius]..  
  
 
These instructions are based on a simple Domain Model which describes basic concepts about families.  
 
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 the members of a family and their parental relationships on a graphical diagram. It will also provide tools to edit the model from the diagram.
+
The modeling workbench created with this tutorial will allow users to visualize the members of a family and their parental relationships on a graphical diagram. It will also provide tools to create new persons from the diagram.
  
 
[[File:sirius_4mtuto_01.png]]
 
[[File:sirius_4mtuto_01.png]]
  
  
'''Note:''' The screenshots have been updated with Obeo Designer 8.1 (based on Sirius 3.1)
+
'''Note:''' The screenshots have been updated with [http://www.obeodesigner.com Obeo Designer 10.0] (based on Sirius 5.0)
 +
 
 +
'''Note:''' Two videos playing this tutorial have been recorder by Xianling Ye. You can watch them here:
 +
* https://www.youtube.com/watch?v=EkRINRRZ1kA
 +
* https://www.youtube.com/watch?v=TVIhiaUduO0
  
 
=Install the sample Domain Model=
 
=Install the sample Domain Model=
Line 27: Line 32:
  
 
[[File:sirius_4mtuto_02.png]]
 
[[File:sirius_4mtuto_02.png]]
 +
 +
 +
'''Note''': If you need to learn how to define such a Domain Model, just follow the [[Sirius/Tutorials/DomainModelTutorial|Domain Model tutorial]]
  
 
== Import the projects containing the sample Domain Model==
 
== Import the projects containing the sample Domain Model==
Line 41: Line 49:
  
 
And then go back to the Examples wizard.
 
And then go back to the Examples wizard.
 
 
A third solution to get these projects consists in importing them from this archive: http://eclipse.org/sirius/doc/resources/getstarted/basicfamily.zip (menu ''File > Import > Existing Projects into Workspace'' to install these projects).
 
 
[[File:sirius_4mtuto_02-2.png]]
 
  
 
==Launch a new runtime from your Eclipse==
 
==Launch a new runtime from your Eclipse==
  
 
To launch a new eclipse application click on ''Run / Run Configurations'' and double click on ''Eclipse Application'' to get a New_configuration.  
 
To launch a new eclipse application click on ''Run / Run Configurations'' and double click on ''Eclipse Application'' to get a New_configuration.  
In order to comfortably run Sirius in your new runtime, you should add this option in your VM arguments :  
+
 
 +
'''If you are not running with java 8''', in order to comfortably run Sirius in your new runtime, you should add this option in your VM arguments :  
 
   -XX:MaxPermSize=256m  
 
   -XX:MaxPermSize=256m  
  
Line 64: Line 68:
 
This perspective provides specific Sirius menus and a new kind of project (''Modeling Project''). A Modeling Project contains models and the corresponding graphical representations created with Sirius.
 
This perspective provides specific Sirius menus and a new kind of project (''Modeling Project''). A Modeling Project contains models and the corresponding graphical representations created with Sirius.
  
==Import a sample model==
+
==Install a sample model==
  
 
A sample model is available from the provided examples (menu ''File > New > Example...'' : select ''Basic Family Sample Model'').
 
A sample model is available from the provided examples (menu ''File > New > Example...'' : select ''Basic Family Sample Model'').
Line 79: Line 83:
  
 
[[File:sirius_4mtuto_11.png]]
 
[[File:sirius_4mtuto_11.png]]
 
 
'''If you don't find these projects from this wizard''':
 
 
Please install the Sirius Samples (see [[Sirius/Tutorials/4MinTutorial#Import_the_projects_containing_the_sample_Domain_Model  | Import the projects containing the sample Domain Model]])
 
 
 
A third solution to get this sample model consists in creating a new ''Modeling Project'' from the ''Model Explorer'':
 
 
[[File:sirius_4mtuto_04.png]]
 
 
Give a name to this sample project.
 
 
[[File:sirius_4mtuto_05.png]]
 
 
Then download the XMI file ''example.basicfamily'': http://eclipse.org/sirius/doc/resources/getstarted/example.basicfamily
 
 
And import this sample file into the new ''Modeling Project'' (menu ''File > Import > File System'').
 
  
 
=Start creating a diagram editor with Sirius=
 
=Start creating a diagram editor with Sirius=
Line 105: Line 91:
  
 
The sample model imported previously will be used to test this editor.
 
The sample model imported previously will be used to test this editor.
 +
 +
'''Note''': the solution of the following steps can be installed directly from the samples
 +
 +
[[File:sirius_4mtuto_52.png]]
 +
  
 
==Create a Viewpoint Specification Project==
 
==Create a Viewpoint Specification Project==
Line 121: Line 112:
  
  
The Viewpoint Specification Project creation wizard creates a new project containing a ''.odesign'' file that describes a modeling workbench which can be interpreted by the Sirius runtime.
+
The Viewpoint Specification Project creation wizard creates a new project containing a ''.odesign'' file. This file describes the modeling workbench that you are going to create. It will be interpreted by the Sirius runtime.
  
 
Sirius automatically opens this file with a specific editor.
 
Sirius automatically opens this file with a specific editor.
Line 127: Line 118:
 
[[File:sirius_4mtuto_15.png]]
 
[[File:sirius_4mtuto_15.png]]
  
==Define a Viewpoint==
+
In this file the wizard has created a first ''viewpoint'' named ''MyViewpoint''. A viewpoint provides a set of representations (diagrams, tables or trees) that the end user will be able to instantiate.
  
A .odesign file contains ''viewpoints''. Each ''viewpoint'' defines a set of ''representations'' (diagrams, tables or trees).
+
Rename this viewpoint to <code>persons</code>.
  
That’s why you need to define at least one viewpoint in the ''.odesign'' file (menu ''New... / 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 (here: <code>basicfamily</code>).
 
+
[[File:sirius_4mtuto_16.png]]
+
 
+
 
+
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.
+
  
 
[[File:sirius_4mtuto_17.png]]
 
[[File:sirius_4mtuto_17.png]]
Line 146: Line 130:
 
*'''Id''': The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.
 
*'''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.
 
*'''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».
+
*'''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 <code>uml ecore</code>.
 +
 
 +
 
 +
Before going forward, you have to declare the required metamodels (those that declare the types used by the modeling tool).
 +
 
 +
Just open the ''MANIFEST.MF'' file of your project and add the plug-in that defines the metamodels (here: ''org.eclipse.sirius.sample.basicfamily'') in the list of the ''Required Plug-ins'' (in the ''Dependencies'' tab).
 +
 
 +
[[File:sirius_4mtuto_51.png]]
  
 
==Define a Diagram==
 
==Define a Diagram==
  
Add a first ''Diagram'' to your ''Viewpoint'' (menu ''New Representation... / Diagram Description'').
+
Add a ''Diagram'' to your ''Viewpoint'' (menu ''New Representation... / Diagram Description'').  
  
 
[[File:sirius_4mtuto_18.png]]
 
[[File:sirius_4mtuto_18.png]]
  
  
A diagram must be associated to a Domain Class: the diagram will graphically represent instances of this Domain Class.
+
We will configure this diagram to graphically represent instances of ''Persons''.
 +
 
 +
Start by associating the metamodel that defines the types used by this diagram: in the ''Metamodel'' tab, select ''basicfamily'' metamodel from the registry.
 +
 
 +
[[File:sirius_4mtuto_18-2.png]]
 +
 
  
At this step, create ''Persons Diagram'' which will display the persons of a family.
+
Then, define the properties of ''Persons Diagram'':
  
 
[[File:sirius_4mtuto_19.png]]
 
[[File:sirius_4mtuto_19.png]]
Line 165: Line 161:
 
*'''Id''': The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.
 
*'''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.
 
*'''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.
+
*'''Domain Class''': The type of the elements from which the user will be able to create the diagram ([packageName]::[className]). The elements displayed on this diagram will be computed from this root element.
 
*'''Initialisation''': If set to true, the representation will be automatically created when creating a new session.
 
*'''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.
 
*'''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.
Line 173: Line 169:
 
==Add a Node to the Layer==
 
==Add a Node to the Layer==
  
A ''Diagram'' shows ''Nodes'' which are elements of the model. To create a new ''Node'' to the diagram, right-click on the ''Layer'' and select the menu ''New Diagram Element... / Node''.  
+
A ''Diagram'' shows ''Nodes'' which are elements of the model. To create a new ''Node'' to the diagram, right-click on the '''Default''' ''Layer'' and select the menu ''New Diagram Element... / Node''.  
  
 
[[File:sirius_4mtuto_21.png]]
 
[[File:sirius_4mtuto_21.png]]
  
'''Note''': Before Sirius 3.0, you have to manually create the layer.
+
'''Note''': Before Sirius 3.0, you have to manually create the Default layer.
  
 
All created nodes must have an ''Id'' and must be associated to a ''Domain class''.
 
All created nodes must have an ''Id'' and must be associated to a ''Domain class''.
Line 187: Line 183:
 
*'''Id''': The identifier of this element. Must be unique. Changing this identifier will break existing user models which reference the old identifier.
 
*'''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.
 
*'''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.
+
*'''Domain Class''': The type of the model element that the node will display.
 
*'''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.
 
*'''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.
  
  
 +
'''Note''': if the ''Semantic Candidates Expression'' is not specified (empty), Sirius uses the ''eAllContents()'' method to retrieve instances. This could lead to poor performance. You should always try to specify an expression that returns only the expected instances.
  
The ''Semantic Candidates Expression'' can be an AQL (Acceleo Query Language) expression prefixed by ''aql:'' . This expression is evaluated on the object associated to the diagram (here: an instance of Family).
+
The ''Semantic Candidates Expression'' should be an AQL (Acceleo Query Language) expression prefixed by ''aql:'' . This expression is evaluated on the object associated to the diagram (here: an instance of Family).
  
'''Note:''' To improve the performance of your modeling tool, we encourage you to declare your metamodel in your project. Just open the ''MANIFEST.MF'' file and add the plug-in that defines your metamodel in the list of the ''Required Plug-ins'' (in the ''Dependencies'' tab). It is '''required''' if your AQL expressions directly refers types of the metamodel (ex: <code>basicfamily::Man</code>).
+
In most cases, you can also use three interpreters dedicated to very simple expressions (direct access to a feature, a variable or a service), by using specific tags (''feature:'' , ''service:'' and ''var:'') followed by the name of the feature, service or variable.
 
+
[[File:sirius_4mtuto_25.png]]
+
  
  
Sirius expressions can also be written in Acceleo 3, contained between [ and /].
+
Sirius expressions can also be written in Acceleo 3, contained between [ and /]. But AQL expressions are more easy to write and are interpreted faster by Sirius.
 
+
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.
+
  
  
Line 215: Line 207:
  
 
[[File:sirius_4mtuto_24.png]]
 
[[File:sirius_4mtuto_24.png]]
 +
 +
== Test your Sirius expression with the interpreter ==
 +
 +
To tune-up Sirius expressions, we encourage you to use the '''Interpreter''' view (menu ''Window > Show View'').
 +
 +
It allows you to enter expressions and evaluate them on the EMF object selected in your ''Model Explorer'' (to evaluate Sirius expressions, please select the ''Sirius'' interpreter).
 +
 +
[[File:sirius_4mtuto_24-2.png]]
 +
 +
 +
'''Tip:''' you can also evaluate an expression on an object selected from a Sirius diagram. But then the interpreter evaluates the expression on the <u>graphical object</u>. To get the <u>semantic object</u> from the graphical object, please use the ''target'' reference (ex: <code>aql:self.target.name.toUpper()</code>).
  
 
==Set a Style to the Node==
 
==Set a Style to the Node==
Line 230: Line 233:
  
  
The ''Style'' also defines the label of the ''Node''. By default the label is calculated with the expression feature '':name''.
+
The ''Style'' also defines the label of the ''Node''. By default the label is calculated with the expression <code>feature:name</code>.
  
 
By using AQL syntax you can enter your own expression. For example, you could display the name to upper case by specifying the Label Expression to <code>aql:self.name.toUpper()</code>
 
By using AQL syntax you can enter your own expression. For example, you could display the name to upper case by specifying the Label Expression to <code>aql:self.name.toUpper()</code>
  
+
You can also specify the default size of the node. Enter <code>5</code> and <code>10</code> for ''Height'' and ''Width''.
 +
 
 +
[[File:sirius_4mtuto_26-2.png]]
 +
 
 +
 
 
Properties of a Node Style
 
Properties of a Node Style
 
*'''Label Format''': The font formatting style to use for the label
 
*'''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.
+
*'''Label Position''': Pick either <code>node</code> position which means ‹inside the node› or <code>border</code> 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.
+
*'''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 Alignment''': The alignment of the label.
 
*'''Label Expression''':  
 
*'''Label Expression''':  
Line 247: Line 254:
  
 
== Test the diagram ==
 
== Test the diagram ==
To test this first diagram, right-click in the ''Model Explorer'' view on the Modeling project and select the menu ''Viewpoint Selection''.  
+
To test this first diagram you can instantiate it on the family contained in the sample model.
  
[[File:sirius_4mtuto_27.png]]
+
There exist two ways to instantiate a representation with Sirius.
  
 +
=== Via the aird editor ===
 +
Double-click on the ''representations.aird'' file in the ''Model Explorer'' to open an editor that shows the models contained in the current ''Modeling Project'' and the corresponding representations.
  
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.
+
[[File:Sirius_4mtuto_27-2.png]]
  
[[File:sirius_4mtuto_28.png]]
 
  
 +
Click on ''New'' in the ''Representations'' panel to open a creation wizard.
  
Then right-click on the sample model and select the menu ''New Representation / new Persons diagram''.
+
Select the ''Persons diagram'', then click on ''Next''.
 +
 
 +
[[File:Sirius_4mtuto_27-3.png]]
 +
 
 +
 
 +
Select the instance of ''Family'' (the type corresponding to ''Persons diagram''), then click on ''Finish''.
 +
 
 +
[[File:Sirius_4mtuto_27-4.png]]
  
[[File:sirius_4mtuto_29.png]]
 
  
  
Line 267: Line 282:
  
 
[[File:sirius_4mtuto_29-2.png]]
 
[[File:sirius_4mtuto_29-2.png]]
 +
 +
 +
=== Via the Model Explorer ===
 +
 +
You can also create representations directly from the ''Model Explorer''.
 +
 +
Right-click in the ''Model Explorer'' view on the Modeling project and select the menu ''Viewpoint Selection''.
 +
 +
[[File:sirius_4mtuto_27.png]]
 +
 +
 +
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.
 +
 +
[[File:sirius_4mtuto_28.png]]
 +
 +
 +
Note that when you use the ''aird editor'', creating a representation from a disabled viewpoint, automatically enables this viewpoint.
 +
 +
 +
Then right-click on the sample model and select the menu ''New Representation / new Persons diagram''.
 +
 +
[[File:sirius_4mtuto_29.png]]
  
 
==Improve the Style of the Node==
 
==Improve the Style of the Node==
  
 
To improve the rendering of the diagram, it is possible to display nodes with images.
 
To improve the rendering of the diagram, it is possible to display nodes with images.
 +
 +
Download this archive containing images [[File:BasicfamilyIcons.zip ]] and unzip its content (''man.svg'' and ''woman.svg'') into a new ''icons'' folder.
 +
 +
Update the manifest file (''MANIFEST.MF''), to include the ''icons'' folder into the binary build.
 +
 +
[[File:sirius_4mtuto_31-2.png]]
 
   
 
   
In our example, delete the ''Square'' style created previously and replace it by a ''Workspace Image''.
+
 
 +
Now that you have images available, delete the ''Square'' style created previously and replace it by a ''Workspace Image''.
  
 
[[File:sirius_4mtuto_30.png]]
 
[[File:sirius_4mtuto_30.png]]
Line 279: Line 323:
 
Specify the ''Workspace Path'' to define the image (the image can be placed in a specific folder of your project).
 
Specify the ''Workspace Path'' to define the image (the image can be placed in a specific folder of your project).
  
Download this archive [[File:png-files.zip ]] and unzip its content (''man32.png'' and ''woman32.png'') into a new ''icons'' folder.
 
  
  
Line 286: Line 329:
  
 
Properties of a Workspace Image:
 
Properties of a Workspace Image:
*'''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.
+
*'''Workspace Path''': Path for the image in the form of <code>/myProjectID/path/to/image.png</code>. 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.
 
*'''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.
+
In the ''Label'' tab,  
 +
* Deselect the ''Show icon'' option to avoid displaying two images for each node.
 +
* Set ''Label Position'' open to <code>Border</code> instead of <code>Node</code>
  
 
[[File:sirius_4mtuto_32.png]]
 
[[File:sirius_4mtuto_32.png]]
 +
 +
 +
In the ''Advanced'' tab,
 +
* Set the ''Size Computation Expression'' to <code>4</code>.
 +
 +
[[File:sirius_4mtuto_32-2.png]]
  
 
==Add a second Node==
 
==Add a second Node==
Line 301: Line 352:
  
  
Saving the ''.odesign'' file immediately updates the current diagram to reflect the changes.
+
Saving the ''.odesign'' file immediately updates the current diagram to reflect the changes.  
 +
 
 +
'''Note''': In development mode, after changing the style, you should recreate the representation in order to get the correct size.
 +
 
  
 
[[File:sirius_4mtuto_34.png]]
 
[[File:sirius_4mtuto_34.png]]
Line 350: Line 404:
 
==Create a Section==
 
==Create a Section==
  
Add a new ''Section'' to the ''Layer'' (menu ''New tool... / Section'').
+
Add a new ''Section'' named ''Tools'' to the ''Layer'' (menu ''New tool... / Section'').
  
 
[[File:sirius_4mtuto_41.png]]
 
[[File:sirius_4mtuto_41.png]]
 
  
 
==Add a Node Creation==
 
==Add a Node Creation==
Line 450: Line 503:
 
Its properties can be edited using the Properties view.
 
Its properties can be edited using the Properties view.
  
[[Category:Sirius]]
+
You can now copy, paste and adapt this tool to provide a ''createWoman'' tool.
  
 
= Going Further =
 
= Going Further =
  
This starter tutorial is now finished, congratulations! If you wish to go further and explore advanced Sirius features, you can continue with the [[Sirius/Tutorials/AdvancedTutorial|advanced tutorial]] which builds on this example.
+
This starter tutorial is now finished, congratulations!  
 +
 
 +
 
 +
If you wish to go further and explore advanced Sirius features, you can continue with the [[Sirius/Tutorials/AdvancedTutorial|advanced tutorial]] which builds on this example.
 +
 
 +
 
 +
Before learning new Sirius features, you can rather see right now how to distribute a graphical modeling tool created with Eclipse Sirius by: [[Sirius/Tutorials/UpdateSiteTutorial|creating an Eclipse updatesite]]

Latest revision as of 08:04, 13 September 2018

Overview

This tutorial explains how to create your first modeling workbench with Eclipse 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 the members of a family and their parental relationships on a graphical diagram. It will also provide tools to create new persons from the diagram.

Sirius 4mtuto 01.png


Note: The screenshots have been updated with Obeo Designer 10.0 (based on Sirius 5.0)

Note: Two videos playing this tutorial have been recorder by Xianling Ye. You can watch them here:

Install the sample 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 a Domain Model (DSL) defining the basic concepts of families:

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

Sirius 4mtuto 02.png


Note: If you need to learn how to define such a Domain Model, just follow the Domain Model tutorial

Import the projects containing the sample Domain Model

The domain model is implemented with several EMF projects that you need to import into your workspace.

These projects can be easily installed from the provided examples (menu File > New > Example... : select Basic Family Metamodel Definition).

Sirius 4mtuto 02-1.png


If you don't find these projects from this wizard, please install the Sirius Samples feature from Sirius updatesite (see the list of Sirius udpate sites for the latest release).

Sirius 4mtuto 02-3.png

And then go back to the Examples wizard.

Launch a new runtime from your Eclipse

To launch a new eclipse application click on Run / Run Configurations and double click on Eclipse Application to get a New_configuration.

If you are not running with java 8, in order to comfortably run Sirius in your new runtime, you should add this option in your VM arguments :

 -XX:MaxPermSize=256m 

Sirius 4mtuto 03.png

Select the Sirius perspective

In the new Eclipse runtime, select the Sirius perspective.

Sirius 4mtuto 06.png


This perspective provides specific Sirius menus and a new kind of project (Modeling Project). A Modeling Project contains models and the corresponding graphical representations created with Sirius.

Install a sample model

A sample model is available from the provided examples (menu File > New > Example... : select Basic Family Sample Model).

Sirius 4mtuto 04-1.png

The wizard then installs a Modeling Project containing a file named example.basicfamily.

Sirius 4mtuto 05-2.png

Double-clicking on this sample model opens a tree editor generated by EMF.

This editor allows you to see the properties and relationships of the model elements.

Sirius 4mtuto 11.png

Start creating a diagram editor with Sirius

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

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

The sample model imported previously will be used to test this editor.

Note: the solution of the following steps can be installed directly from the samples

Sirius 4mtuto 52.png


Create a Viewpoint Specification Project

A Viewpoint Specification Project will contain the definition of your modeling workbench. It 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 this project in the same Eclipse runtime launched previously.


Sirius 4mtuto 12.png


Give a name to this project.

Sirius 4mtuto 05.png


The Viewpoint Specification Project creation wizard creates a new project containing a .odesign file. This file describes the modeling workbench that you are going to create. It will be interpreted by the Sirius runtime.

Sirius automatically opens this file with a specific editor.

Sirius 4mtuto 15.png

In this file the wizard has created a first viewpoint named MyViewpoint. A viewpoint provides a set of representations (diagrams, tables or trees) that the end user will be able to instantiate.

Rename this viewpoint to persons.

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 (here: basicfamily).

Sirius 4mtuto 17.png


Properties of a Viewpoint

  • 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.


Before going forward, you have to declare the required metamodels (those that declare the types used by the modeling tool).

Just open the MANIFEST.MF file of your project and add the plug-in that defines the metamodels (here: org.eclipse.sirius.sample.basicfamily) in the list of the Required Plug-ins (in the Dependencies tab).

Sirius 4mtuto 51.png

Define a Diagram

Add a Diagram to your Viewpoint (menu New Representation... / Diagram Description).

Sirius 4mtuto 18.png


We will configure this diagram to graphically represent instances of Persons.

Start by associating the metamodel that defines the types used by this diagram: in the Metamodel tab, select basicfamily metamodel from the registry.

Sirius 4mtuto 18-2.png


Then, define the properties of Persons Diagram:

Sirius 4mtuto 19.png


Properties of a Diagram

  • 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 elements from which the user will be able to create the diagram ([packageName]::[className]). The elements displayed on this diagram will be computed from this root element.
  • 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.

Add a Node to the Layer

A Diagram shows Nodes which are elements of the model. To create a new Node to the diagram, right-click on the Default Layer and select the menu New Diagram Element... / Node.

Sirius 4mtuto 21.png

Note: Before Sirius 3.0, you have to manually create the Default layer.

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

Sirius 4mtuto 22.png


Properties of a Node

  • 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 model element that the node will display.
  • 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.


Note: if the Semantic Candidates Expression is not specified (empty), Sirius uses the eAllContents() method to retrieve instances. This could lead to poor performance. You should always try to specify an expression that returns only the expected instances.

The Semantic Candidates Expression should be an AQL (Acceleo Query Language) expression prefixed by aql: . This expression is evaluated on the object associated to the diagram (here: an instance of Family).

In most cases, you can also use three interpreters dedicated to very simple expressions (direct access to a feature, a variable or a service), by using specific tags (feature: , service: and var:) followed by the name of the feature, service or variable.


Sirius expressions can also be written in Acceleo 3, contained between [ and /]. But AQL expressions are more easy to write and are interpreted faster by Sirius.


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

Sirius 4mtuto 23.png


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.

Sirius 4mtuto 24.png

Test your Sirius expression with the interpreter

To tune-up Sirius expressions, we encourage you to use the Interpreter view (menu Window > Show View).

It allows you to enter expressions and evaluate them on the EMF object selected in your Model Explorer (to evaluate Sirius expressions, please select the Sirius interpreter).

Sirius 4mtuto 24-2.png


Tip: you can also evaluate an expression on an object selected from a Sirius diagram. But then the interpreter evaluates the expression on the graphical object. To get the semantic object from the graphical object, please use the target reference (ex: aql:self.target.name.toUpper()).

Set a Style to the Node

To define the way the node is graphically represented on the diagram, it must declare a Style (menu New Style).

Here, we have chosen a square to represent a Man.

Sirius 4mtuto 25.png


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

Sirius 4mtuto 26.png


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

By using AQL syntax you can enter your own expression. For example, you could display the name to upper case by specifying the Label Expression to aql:self.name.toUpper()

You can also specify the default size of the node. Enter 5 and 10 for Height and Width.

Sirius 4mtuto 26-2.png


Properties of a Node Style

  • Label Format: The font formatting style to use for the label
  • Label Position: Pick either node position which means ‹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.

Test the diagram

To test this first diagram you can instantiate it on the family contained in the sample model.

There exist two ways to instantiate a representation with Sirius.

Via the aird editor

Double-click on the representations.aird file in the Model Explorer to open an editor that shows the models contained in the current Modeling Project and the corresponding representations.

Sirius 4mtuto 27-2.png


Click on New in the Representations panel to open a creation wizard.

Select the Persons diagram, then click on Next.

Sirius 4mtuto 27-3.png


Select the instance of Family (the type corresponding to Persons diagram), then click on Finish.

Sirius 4mtuto 27-4.png


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.

Sirius 4mtuto 29-2.png


Via the Model Explorer

You can also create representations directly from the Model Explorer.

Right-click in the Model Explorer view on the Modeling project and select the menu Viewpoint Selection.

Sirius 4mtuto 27.png


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.

Sirius 4mtuto 28.png


Note that when you use the aird editor, creating a representation from a disabled viewpoint, automatically enables this viewpoint.


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

Sirius 4mtuto 29.png

Improve the Style of the Node

To improve the rendering of the diagram, it is possible to display nodes with images.

Download this archive containing images File:BasicfamilyIcons.zip and unzip its content (man.svg and woman.svg) into a new icons folder.

Update the manifest file (MANIFEST.MF), to include the icons folder into the binary build.

Sirius 4mtuto 31-2.png


Now that you have images available, delete the Square style created previously and replace it by a Workspace Image.

Sirius 4mtuto 30.png


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


Sirius 4mtuto 31.png


Properties of a Workspace Image:

  • 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.
  • Set Label Position open to Border instead of Node

Sirius 4mtuto 32.png


In the Advanced tab,

  • Set the Size Computation Expression to 4.

Sirius 4mtuto 32-2.png

Add a second Node

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

Sirius 4mtuto 33.png


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

Note: In development mode, after changing the style, you should recreate the representation in order to get the correct size.


Sirius 4mtuto 34.png

Add a Relation Based Edge

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

Sirius 4mtuto 36.png


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, Sirius will evaluate the Target Finder Expression on each Source Mapping to detect the corresponding Target Mapping.

Sirius 4mtuto 37.png


Properties of a Relation Based Edge

  • 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.

Sirius 4mtuto 38.png


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

Sirius 4mtuto 39.png


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

Sirius 4mtuto 40.png

Add a Palette for edition tools

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.

Create a Section

Add a new Section named Tools to the Layer (menu New tool... / Section).

Sirius 4mtuto 41.png

Add a Node Creation

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 element to the Section (menu New Element Creation... / Node Creation Description).

Sirius 4mtuto 42.png


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).

Sirius 4mtuto 43.png


Properties of a Node Creation

  • 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.


Define 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 Change Context element to define the context of the actions.

Sirius 4mtuto 44.png


The Change Context 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).

Sirius 4mtuto 45.png


Properties of a Change Context

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


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

Sirius 4mtuto 46.png


Specify the type of the new instance and how it will be attached to the context.

Sirius 4mtuto 47.png


Properties of a Create 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 also add a Set Value operation.

Sirius 4mtuto 48.png


For example, the following AQL expression will compute a default name depending on the number of men already created. aql:'man'+container.members->filter(basicfamily::Man)->size()

Note: As this AQL expression directly refers a type of the metamodel, you have to add the basicfamily metamodel to the list of your project's required plug-ins (see Add a Node to the Layer).

Sirius 4mtuto 49.png


Properties of a Set Value

  • Feature Name: Name of the feature to set.
  • Value Expression: Expression returning the value to set on the current element.

Test 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 a createMan tool

You can click on this tool 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.

Sirius 4mtuto 50.png


Its properties can be edited using the Properties view.

You can now copy, paste and adapt this tool to provide a createWoman tool.

Going Further

This starter tutorial is now finished, congratulations!


If you wish to go further and explore advanced Sirius features, you can continue with the advanced tutorial which builds on this example.


Before learning new Sirius features, you can rather see right now how to distribute a graphical modeling tool created with Eclipse Sirius by: creating an Eclipse updatesite

Back to the top