plugins/org.eclipse.sirius.doc/doc/user/general/Aird_Editor.textile

h1. Aird Editor

This document describes the new form-based editor for @aird@ files introduced in version 5.0. This editor is associated to @*.aird@ files (which contains Sirius representations data) and provides end-users complete overview of their models and representations, and direct access to the most common operations.

This document assumes you are already faimiliar with the vocabulary associated with Sirius; if that is not the case, please refer to "the Modeling Project documentation":Modeling%20Project.html which describes in details the more "traditional" Sirius UI and the associated concepts.

_Note:_ This new editor has been introduced with Sirius 5.0. While it is already functional, it should be considered as a first iteration, and its UI is subject to change without warnings in later versions based on experience and user feedback.

{toc:style=disc|minLevel=2|maxLevel=3}

h2(#overview). Overview

The traditional Sirius UI is centered on the _Modeling_ perspective, and in particular on the _Model Explorer_ view. For some use cases, especially when Sirius representations are not the primary focus of the user but only a secondary feature to support their main task, this reliance on a specific perspective or view can be inconvenient. The Aird editor is designed to provide an alternative UI to interact with Sirius that is better suited for these use cases. Because the editor is available from any perspective and directly exposes the most common user operations inside its UI, it makes it more convenient to use Sirius in a variety of contexts.

Note that most of the features available from the aird editor are also available from the _Model Explorer_'s UI; the editor simply provides alternative ways to use them that can be more convenient in some contexts. There are two exceptions, described in more details below, which are currently specific to the Aird editor: the generic "model creation wizard":#model_creation_wizard and the ability to "add/remove elements directly":#quick_editing from the semantic models.

Using Sirius to display and manipulate your domain models requires telling Sirius:
* which are the models (files) your are interested in;
* which of the compatible representation types you want to make use of.

Representation types are defined in plug-ins which extend Sirius and that you need to install in your environment. Which ones will be available to you depend on what concrete modelers you have installed. Sirius-based modelers can provide many alternative representation types for the same semantic models, and organize them in _viewpoints_, which corresponds to the different activities or point of views that can be applied to the models.

This organization is reflected in the editor, which presents two main blocks:

!images/aird_editor_full.png!

On the left, the _Models_ block shows the raw semantic models, which can come from multiple files (resources), and allows you to configure which models should be loaded, to navigate inside them, to perform some basic editing tasks, and finally to create and manage Sirius representations on them.

On the right the _Representations_ block displays all the types of representations available and all the concrete ones already created, organized by viewpoint (by default). It also allows you to manage the representations and viewpoints. The representation types available to you will depend both on the kind of models you have loaded and which modeler plug-ins you have installed in your environment. For example if you have installed "UML Designer":http://www.umldesigner.org/ *and* have at least one @*.uml@ model loaded, you will find there the different kinds of UML diagrams implemented in _UML Designer_.

h2(#opening). Opening the Aird Editor

The Aird editor is the default editor associated to the @*.aird@ files in Eclipse. In some perspectives (e.g. _Java_), double-clicking on an @aird@ file will open the editor and automatically load all the files/models needed if that it not already the case. In other contexts where double-click performs a different operation you may need to open the context menu and select __Open With > Aird Editor__.

It is also possible to configure Sirius to automatically open the Aird editor when an @*.aird@ file is first loaded. When this mode is enabled, opening/expanding a _Modeling Project_ from the _Model Explorer_, which triggers the loading of the models, will also open the editor. This behavior can be enabled via the Sirius preference *__Automatically open the aird editor when an aird file is loaded__*: 

!images/aird_editor_pref.png!

When this preference is activated, then aird editor is opened automatically in the following situations:

* After clicking __Finish__ button of the __Create a modeling project__ wizard, the project is created as well as its aird file. The newly created aird file is automatically opened in the editor.

!images/aird_editor_modeling_project_creation_wizard.png!

* When a project with the _Modeling_ nature is opened from __Model Explorer__ or __Project Explorer__, the aird editor is also automatically opened if it contains a main aird file.

!images/aird_editor_open_project_modeling_explorer.png!

* When the aird file is first expanded from a project with _Modeling_ nature from __Model Explorer__ or __Project Explorer__ view, the aird editor is also opened automatically. 

!images/aird_editor_expand_aird_file.png!

h2(#closing). Closing the Aird Editor and unloading models

You have four different ways to close the aird editor. But not all the ways have the same behaviour.

There is one thing to take in consideration when it comes to close the aird editor:

* An opened aird editor has all its referenced models loaded in memory as well as any representation opened in a Sirius editor. For big models and big representations, this can have a big memory footprint. So when you want to close the aird editor you must ask yourself if you want to free the memory used by the loaded aird or not. Then you have to choose the right way to close the editor accordingly. Indeed some way to close the editor will not free this memory and some others will.

The closing mechanism which does not unload models and representations is the following:

* Clicking on the editor white cross on the top right corner of editor's tab. This will only close the aird editor and will not free memory used by loaded models and representations opened in Sirius editors.

!images/aird_editor_close_editor_with_cross.png!

The closing mechanisms which do unload models and representations from memory are the following:

* If your aird editor refers to an aird file on a _Modeling Project_, the only way to unload models and representations from memory is to close it.

* If your aird editor does not refer to an aird file on a _Modeling Project_, a button _Unload models_ is provided by the editor and allows to close the aird editor and free memory used by loaded models and representations.

!images/aird_editor_close_editor_with_button.png!

* When aird editor is not in a _Modeling Project_, _Close_ action in contextual menu of the aird file is available. This action is reachable in any view showing the aird as an IFile like _Model Explorer_, _Package Explorer_ etc... 

!images/aird_editor_close_editor_with_right_click.png!

h2(#semantic_models). Managing the Semantic Models

This section describes how to manage the semantic models associated to your aird file, which are visible in the _Models_ block on the left side of the editor:

!images/aird_editor_models_block.png!

The _Models_ block displays a tree showing all semantic models associated to the aird file, organized in two categories:
* The models located in the same workspace project as the one containing the aird file from which editor has been opened. These are visible as root items on the graphical tree.

* The models located in a project that is different from the project containing the aird file from which the editor has been opened. These models are visible under the _Project Dependencies_ category.

For example:

!images/aird_editor_model_loading.png!

Regardless of the category they appear in, all the semantic models associated with an aird file are fully loaded, and you can expand the tree elements to navigate inside your models. The tree can be filtered on the elements labels using the search box at the top to quickly locate specific model elements:

!images/aird_editor_filter_models_elements.png!

In addition to the actual semantic elements, this view also includes all existing representations (diagrams, tables, trees). As in the case of the _Model Explorer_, the representations are available directly below the semantic element they represent, and can be opened by double-clicking on them.

h3. Loading an Existing Model

To be able to edit a semantic model with a Sirius modeler, you must first tell the aird it can edit that model. There are two mechanisms to do so:
* An automatic one were, if your project has _Modeling_ nature, any model file added inside the project will be automaticall added to the aird file.
* A manual one were you have two different buttons in the editor:
** The *__New...__* button, which opens a wizard allowing to create a new model from any registered package and in any project you want (see the next section for more details on the wizard). The newly created model will be loaded automatically in the aird file.
** The *__Add__* button, which allows to load into the aird file an already existing model either from the same project or from another one.
Note that you can also add a new semantic model to a session by simply drag and dropping the model file from the workpace (from any Eclipse view) into the _Models_ block on the left side of the editor.


h3(#model_creation_wizard). Creating New Models

The aird editor features a generic model creation wizard that can be used to create new models files of any kind supported in the environement (i.e. instances of any installed meta-model). To create a new model, select the __New...__ button. It opens a creation wizard:
* The first page asks you to select which kind of model you want to create. It will present you all the EMF metamodels available in your installation (e.g. UML or BPMN). You can use the text field to filter among all the meta-models available (in large installations, there may be hundreds of them).

!images\aird_editor_create_new_model.png!

* Once the metamodel is selected, the second page asks for the type of the root element in the new model file. By default Sirius will try to infer good candidates for this root element type, and show only those. You can deselect the _Show only suggested root types_ checkbox to reveal *all* the concrete types defined in the metamodel you selected.
* Finally, the third page of the wizard will ask you for the name and location of the new file to create. By default, the file will be created in the same project as the @aird@ file and have a generated name.

h3(#removing_model). Removing Model Dependencies And Representations From The Aird Editor

To remove *models dependencies*, you must select the root model items and click on the *__Remove__* button:

!images/aird_editor_remove_semantic_model.png!

 Note that this action does not delete the physical model file.

The removal can be applied only if some rules are respected. If they are not, the remove button will still be active and its activation, will inform you of the reasons why you cannot proceed the removal.

The rules regarding models dependencies removal are the following :
* A model dependency cannot be removed if at least one of its element contains a representation. Note that the representation can be invisible if the viewpoint providing it is not enabled.

!images/aird_editor_remove_semantic_model_representation.png!

* A model dependency cannot be removed if you are working inside a project with the _Modeling_ nature and the semantic model is located inside this project. Indeed, the _Modeling_ nature ensures that all model files stored inside the project are always loaded in the project's @aird@ file.

* A model dependency cannot be removed if it is a fragment of a model. In this situation you need to use the *__Uncontrol__* action to remove it.

!images/aird_editor_remove_semantic_model_uncontrol.png!

h3(#removing_representation). Removing Representations From The Aird Editor

To remove a *representation* from the aird file, you can either select it in the editor and use the right click contextual action *__Delete__* or the *__DEL__* keyboard key.

h3(#quick_editing). Models Quick Editing

The normal way to display and edit models with Sirius is to do it through one or several Sirius-defined representations (_modelers_), which define domain-specific ways to represent and manipulate the data, and ensure some level of consistency.

In some situations you may need to manipulate the model elements more directly, even if no Sirius-based modeler or tool has been defined to support your use case. The _aird editor_ provides support for "quick editing" of the semantic models independently of a Sirius representation. It works like any generic EMF models editor:
* You can right-click on a semantic element to create new children inside, or to delete it. 
* When you have selected an element, you can use the _Properties_ view to edit its features. Note that the content of this view depends on which _viewpoints_ are currently enabled. If you have enabled viewpoints which define specific properties views for your elements, these will be used instead of a generic one, so not all direct model operations may be available.

Keep in mind that editing the semantic models this way bypasses any high-level restrictions and rules that may be  brought by Sirius modelers. Depending on the semantic models, these direct manipulation may break domain constraints. Use with care.

h2(#representations). Managing Representations and Viewpoints

To use a Sirius modeler to edit a model element, you need to create a graphical representation for it. This representation is then editable with a Sirius modeler that can be a diagram, a tree or a table editor. Concrete representations are created from a _representation type_, which are provided by Sirius-based modelers, and organized by _viewpoints_.

In addition to providing representation types from which representation can be created, viewpoints can also provide extensions to other viewpoints' representation types, adding for example new tools to them.

The following sections describe how to create/remove representations and the related functionalities.

h3(#visualize_viewpoints_representations). Visualizing Viewpoints and Representations

The aird editor has a block named _Representation_ which displays all the available viewpoints (compatible with the semantic models loaded), the representation types they define, and the actual concrete representations that have been created. All these elements are organized in a tree:

!images/aird_editor_representations_block.png!

This _Representations_ block is separated in two parts:
* The left is the tree showing viewpoints with their representations types (showing the number of representations it contains) and representations.
* The right part shows the documentation of the viewpoint of the selected element. It allows to find what viewpoint provides the representation type providing Sirius modeler functionalities fitting your needs to edit graphically your models.

To the bottom of these two parts are two checkboxes, that can be used to control which elements are displayed:
* *__Group representations by viewpoint__*: when active (the default), viewpoints items are shown in the tree. When deactivated, only representation types and their representations are shown.
* *__Show disabled viewpoints__*: when active (the default), *all* the available viewpoints (and their content) which apply to the semantic elements currently loaded are displayed, even if they are currently disabled. This is useful when starting a new project as it shows you immediatly all the features that are available to you, even if you have not yet enabled any. Once you have enabled the viewpoints you need, you may want to hide the others to help focus. 

A viewpoint is grayed out if it is disabled. Otherwise it is enabled in the aird file.

The viewpoints shown are all the viewpoints available in your environment that are compatible with the models loaded in the aird file. So if your environment does not contain any viewpoint compatible with your models or if you have no models loaded, then the graphical representations component will be empty.

Representations can also be seen directly in the models graphical component of the aird editor under the associated model's element if the viewpoint containing the representation type used to create the representation is activated. If not the representation will not be visible.

!images/aird_editor_rep_under_model.png!

To open an exisiting representation, simply double-click on it (this works both in the _Representations_ tree and in the _Semantics_ tree).

h3(#enable_disable_viewpoints). Enabling and Disabling Viewpoints

A viewpoint provides representation types and/or extension for other representation types. In some cases you want need to disable functionalities brought by these extensions or on the contrary to enable them. 

To enable/disable a viewpoint, you can either:
* double click on a viewpoint item on the representations graphical component of the aird editor. It will enable or disable the viewpoint depending on its current state.
* use the *__Enable__* *__Disable__* buttons after having selected one or more viewpoints.
* create a new representation defined in a previously disabled viewpoint. It will activate the viewpoint of the corresponding representation type.

Some viewpoints have dependencies to another ones. Enabling a viewpoint will automatically enable all its dependencies. Disabling a viewpoint that is a dependency of another one will ask you to confirm its disabling as well as the ones depending on it.

h3(#create_remove_representations). Creating and Removing Representations

After having identified the representation type providing Sirius modeler functionalities you need, three methods are available to create a new representation from it and a model element to edit its content:
* First you can double click on a representation type from the representations graphical component of the aird editor. It opens the *__Create a new representation__* wizard. You then have to select a model element compatible with the description from which the new representation will be created.

!images/aird_editor_create_rep_double_click.png!

* Second you can click on the *__New__* button of the representations graphical component of the aird editor. It opens the wizard were you have first to select the representation type from which you want to create a representation before choosing the model element.

* The last method is to use the contextual menu action *__New representation__* available on right click on a model element from the models graphical component:

!images/aird_editor_new_rep_menu.png!

The menu shows only representation types compatible with the selected model element and that belong to activated viewpoints. When choosing *__Other...__* the wizard to create new representation is opened and show the representation types compatible with the selected element whether they belong to a viewpoint activated or deactivated. If you create a representation defined in a viewpoint that was previously disabled, it will be enabled automatically.

You can _remove_ a representation either from the representations or models graphical components of the aird editor by:
* using the __Remove__ action in the representation's context menu;
* using the __Remove__ button of representations block when the representation to remove is selected there; 
* select the representation and hit the __Del__ key.

h3(#open_representation). Opening a Sirius Modeler From a Representation

To open a representation to edit graphically the model's element it is associated to, you just have to double-click on it either in the models or representations graphical component of the aird editor. 

If you double click on a representation in the _Representations_ block that belong to a disabled viewpoint, this viewpoint will automatically be enabled before opening the representation.