Diagram description

Before you Start

🔥 This feature is currently considered experimental. Try it out and give feedback by reporting bugs and suggesting new features. It’s not recommended for production use.

🛠️ This feature is available to studio makers.

This page explains how the View description models diagram editors inside Sirius Web.

1. Introduction

The Diagram representation allows you to create rich graphical editors for your domain models. As with other representation types, it uses the same foundational expression language and styling concepts.

How to create a diagram description in four steps:

  1. Create a Studio project with a View inside.

  2. Create a Diagram Description inside the view.

  3. Configure node and edge descriptions, styles, tools, and palettes.

  4. Save and test; Sirius Web hot-reloads the representation description without code generation.

2. Diagram Description

2.1. Core Properties

Every representation description provides the following fundamentals:

  • name: String A unique identifier of the description. If the name is changed, existing representations created from this description will stop working.

  • domainType: DomainType Fully qualified type of the semantic element on which the representation can be created. For example flow::System or ecore::EClass.

  • preconditionExpression: InterpretedExpression Expression evaluated on the semantic element on which the representation may be created; the representation is available only when it returns true. If the expression is not set, the representation is always available. Here are the variables available for this expression:

    • self: Object The semantic element on which the representation may be created

  • titleExpression: InterpretedExpression Use to compute the default representation label visible when the new representation creation dialog is opened. The end user can choose not to use it and provide instead their own label. This Here are the variables available for this expression:

    • self: Object The semantic element on which the representation may be created

  • iconExpression: InterpretedExpression Used to compute the icon associated with the representation. This expression should return an icon path, for example the path of an image file in the application like aql:'/folder/icon.svg' for an icon available in a specific folder of a maven module.

    • self: Object The semantic element on which the representation is being created

  • description: String Some documentation to let the studio makers understand the purpose of the representation.

  • endUserDocumentation: String Some documentation to let the end users understand the purpose of the representation.

2.2. Structure

The diagram description element can contain two major types of elements: NodeDescription and EdgeDescription. These elements describe the top level nodes and the edges that can be displayed in the diagram.

  • nodeDescriptions: NodeDescription

  • edgeDescriptions: EdgeDescription

2.3. Styling

The diagram description itself can contain styling information.

  • style: DiagramStyleDescription The default style of the diagram

  • conditionalStyles: ConditionalDiagramStyle A list of conditional styles that can be applied to the diagram based on its state

  • decoratorDescriptions: DecoratorDescription A list of decorators that can be applied to some diagram elements. Decorators are used to add additional information or visual cues to the diagram elements thanks to icons and labels

2.4. Interaction

The diagram description can also contain information about the interaction with the diagram, such as the toolbar and palette.

  • toolbar: DiagramToolbar Used to configure the toolbar of the diagram. The toolbar is visible at the top of the diagram and can contain buttons to perform actions on the diagram or its elements.

  • palette: DiagramPalette Used to configure the palette of the diagram. The palette is accessible thanks to a right click on the background of the diagram. It can contain tools to create new elements in the diagram or to perform actions on the diagram or its elements.

  • groupPalette: GroupPalette Used to configure the palette of the diagram when multiple elements are selected. This palette is visible when multiple elements are selected and a right click is performed on the selection. It can contain tools to perform actions on the selected elements.

  • minimapVisible: boolean Used to indicate if the minimap is visible or not. The minimap is a small overview of the diagram that can be used to navigate the diagram quickly.

2.5. Layout

  • layoutOption: DiagramLayoutOption Used to configure the behavior of the automatic layout of the diagram. It can be configured to one of the following values:

    • NONE no automatic layout is applied to the diagram

    • AUTO_LAYOUT the automatic layout is applied to the diagram when the diagram is opened or when the diagram is refreshed

    • AUTO_UNTIL_MANUAL the automatic layout is applied to the diagram when the diagram is opened or when the diagram is refreshed, but it stops being applied when the user starts moving or resizing diagram elements

  • arrangeLayoutDirection: ArrangeLayoutDirection Used to configure the direction in which elements will be arranged when the automatic layout is applied to the diagram. It can be configured to one of the following values:

    • UNDEFINED`

    • RIGHT

    • LEFT

    • UP

    • DOWN

3. Node Description

The NodeDescription describes a node and its children, border nodes, labels, style, visibility and interactions.

3.1. Core Properties

  • name: Identifier A unique identifier of the node description. If the name is changed, existing nodes created from this description will disappear and new nodes will replace them. Existing positions, sizes and customizations done by the end users will be lost.

  • description: String Some documentation to let the studio makers understand the purpose of the node description.

3.2. Rendering

  • semanticCandidatesExpression: InterpretedExpression Used to selected the semantic elements for which a node may be created. The semantic elements selected by this expression will be then filtered by the domainType` and the preconditionExpression.

    • self: Object The current context on which the expression is evaluated. If the node is under the diagram description, it is the semantic element on which the diagram has been created. If the node is under another node description, it is the semantic element on which the parent node has been created.

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • ancestors: List<Object> The list of all the semantic elements used to create the parents of the current node. The first element of the list is the semantic element used to create the parent node, the second element is the semantic element used to create the grandparent node, and so on up until the semantic element of the diagram itself.

    • semanticElementIds: List<String> The list of the identifiers of all semantic elements which should appear with the current description. For node descriptions using an UNSYNCHRONIZED synchronization policy, it can be expensive to consider all the potential semantic elements in the model. This variable can thus be used to consider only the semantic elements which are already present in the diagram and those who would be added by a create view model operation.

    • collapsingState: CollapsingState Indicates if the node is collapsed or expanded.

    • isBorderNode: boolean Indicates if the node being created is a border node or not.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

  • domainType: DomainType Fully qualified type of the semantic elements for which a node should be created. For example flow::System or ecore::EClass. Used to filter the semantic elements selected by the semanticCandidatesExpression.

  • preconditionExpression: InterpretedExpression Used to filter the semantic elements selected by the semanticCandidatesExpression after filtering by domainType.

    • self: Object The current context on which the expression is evaluated. If the node is under the diagram description, it is the semantic element on which the diagram has been created. If the node is under another node description, it is the semantic element on which the parent node has been created.

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • ancestors: List<Object> The list of all the semantic elements used to create the parents of the current node. The first element of the list is the semantic element used to create the parent node, the second element is the semantic element used to create the grandparent node, and so on up until the semantic element of the diagram itself.

    • semanticElementIds: List<String> The list of the identifiers of all semantic elements which should appear with the current description. For node descriptions using an UNSYNCHRONIZED synchronization policy, it can be expensive to consider all the potential semantic elements in the model. This variable can thus be used to consider only the semantic elements which are already present in the diagram and those who would be added by a create view model operation.

    • collapsingState: CollapsingState Indicates if the node is collapsed or expanded.

    • isBorderNode: boolean Indicates if the node being created is a border node or not.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

  • synchronizationPolicy: SynchronizationPolicy Used to configure how the node created from this description will be synchronized with the semantic model. This is especially important when dealing with large models in which the semanticCandidatesExpression could return a very large number of elements. In order to prevent the creation of massive diagrams which are difficult to manipulate, one can use the synchronization policy to take control over the synchronization process. It can be configured to one of the following values:

    • SYNCHRONIZED The node will be automatically created when if a semantic element is returned by the semanticCandidatesExpression. To delete the node, the underlying semantic element must not be reachable by the semanticCandidatesExpression anymore (most of the time, when the semantic element is deleted).

    • UNSYNCHRONIZED The node will not be automatically created when the semantic element is returned by the semanticCandidatesExpression. Instead the node will only be created if a tool explicitely asks for it. In this case, the node can be deleted by another tool without deleting the underlying semantic element. The node will be automatically deleted if the underlying semantic element is not reachable by the semanticCandidatesExpression anymore.

3.3. Labels

Nodes can have multiple labels which can be displayed inside or outside the node. The labels can be configured by an expression to display information about the semantic element, such as its name or type.

3.3.1. Inside Label Description

InsideLabelDescription specializes LabelDescription for labels displayed inside a node. A node description can only have a single inside label description.

Rendering

  • labelExpression: InterpretedExpression Used to compute the text of the label.

    • self: Object The semantic element used as the target of the node being rendered

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • ancestors: List<Object> The list of all the semantic elements used to create the parents of the current node.

    • collapsingState: CollapsingState Indicates if the node is collapsed or expanded.

    • isBorderNode: boolean Indicates if the node being created is a border node or not.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

  • overflowStrategy: LabelOverflowStrategy Used to indicate how the label is supposed to behave if its size becomes larger the the size of the node.

    • NONE The node should grow to display the entire label

    • WRAP The label should be wrapped to create a new line

    • ELLIPSIS The end of the label should be replaced with "…​"

  • textAlign: LabelTextAlign How the text in the label should be aligned

    • LEFT

    • RIGHT

    • CENTER

    • JUSTIFY

  • position: InsideLabelPosition: Used to specify the position of the label within the node

    • TOP_CENTER

    • TOP_LEFT

    • TOP_RIGHT

    • MIDDLE_LEFT

    • MIDDLE_CENTER

    • MIDDLE_RIGHT

    • BOTTOM_LEFT

    • BOTTOM_CENTER

    • BOTTOM_RIGHT

Styling

  • style: InsideLabelStyle

  • conditionalStyles: ConditionalInsideLabelStyle

3.3.2. Outside Label Description

OutsideLabelDescription specializes LabelDescription for labels displayed outside a node. A node description can have multiple outside label description.

Rendering

  • labelExpression: InterpretedExpression Used to compute the text of the label.

    • self: Object The semantic element used as the target of the node being rendered

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • ancestors: List<Object> The list of all the semantic elements used to create the parents of the current node.

    • collapsingState: CollapsingState Indicates if the node is collapsed or expanded.

    • isBorderNode: boolean Indicates if the node being created is a border node or not.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

  • overflowStrategy: LabelOverflowStrategy Used to indicate how the label is supposed to behave if its size becomes larger the the size of the node.

    • NONE The node should grow to display the entire label

    • WRAP The label should be wrapped to create a new line

    • ELLIPSIS The end of the label should be replaced with "…​"

  • textAlign: LabelTextAlign How the text in the label should be aligned

    • LEFT

    • RIGHT

    • CENTER

    • JUSTIFY

  • position: OutsideLabelPosition Where the label can be positioned outside of the node

    • BOTTOM_CENTER

Styling

  • style: OutsideLabelStyle

  • conditionalStyles: ConditionalOutsideLabelStyle

3.4. Structure

A node can contain child nodes and border nodes. To configure this structure, a node description can contain various child node descriptions and reuse existing node descriptions as its children too. One can for example, create a node description that reuses itself as a child node description to create a recursive structure of nodes in a diagram.

  • childrenDescriptions: NodeDescription The list of child node descriptions which can be used to render child nodes

  • borderNodesDescriptions: NodeDescription The list of border node descriptions which can be used to render nodes on the border of the current node.

  • reusedChildNodeDescriptions: NodeDescription The list of existing node descriptions that should be reused as child node descriptions

  • reusedBorderNodeDescriptions: NodeDescription The list of existing node descriptions that should be reused as boder node descriptions

3.5. Styling

  • style: NodeStyleDescription The default style of the node

  • conditionalStyles: ConditionalNodeStyle A list of conditional styles that can be applied to the node based on its state

  • isHiddenByDefaultExpression: InterpretedExpression Used to configure if the node should be hidden by default.

    • self: Object The semantic element used as the target of the node being rendered

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

  • isFadedByDefaultExpression: InterpretedExpression Used to configure if the node should be faded by default.

    • self: Object The semantic element used as the target of the node being rendered

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

3.5.1. Node Style Description

The style of a node being rendered is compute thanks to a node style description. All the node style descriptions are sharing some common properties:

  • description: String Some documentation to let the studio makers understand the purpose of the node style description.

  • childrenLayoutStrategy: LayoutStrategyDescription

  • borderColor: UserColor

  • borderRadius: int

  • borderSize: int

  • borderLineStyle: LineStyle which can take one of the following values

    • SOLID

    • DASH

    • DOT

    • DASH_DOT

Rectangular Node Style Description

Use this node style description to create rectangular nodes. On top of the properties of all node style descriptions, the rectangular one adds the following properties:

  • background: UserColor

Image Node Style Description

Use this node style description to create nodes using an image. On top of the properties of all node style descriptions, the image one adds the following properties:

  • shape: String

  • isPositionDependentRotation: boolean

Icon Label Node Style Description

Use this node style description to create nodes composed of an icon and a label. On top of the properties of all node style descriptions, the icon label one adds the following properties:

  • background: UserColor

Ellipse Node Style Description

Use this node style description to create nodes as an ellipse. On top of the properties of all node style descriptions, the ellipse one adds the following properties:

  • background: UserColor

3.6. Interaction

  • palette: NodePalette Used to configure the palette of the node. This palette is accessible thanks to a right click on a node. It can contain tools to create new elements in the diagram or to perform actions on the node or its target semantic element.

  • actions: Action Used to display actions on the node being rendered. Actions are displayed as a clickable icon to trigger some specific behavior.

3.7. Layout

  • collapsible: boolean Indicate if the node is collapsible. A collapsed node does not display its child nodes.

  • isCollapsedByDefaultExpression: InterpretedExpression Used to indicate if the node should be collapsed by default.

    • self: Object The semantic element used as the target of the node being rendered

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

  • userResizable: UserResizableDirection Used to indicate if the node can be resized by end users.

  • keepAspectRatio: boolean Used to indicate that resizing a node should keep the same aspect ratio. Use it with defaultWidthExpression and defaultHeightExpression to control precisely the size of the node.

  • defaultWidthExpression: InterpretedExpression Used to configure the default width of the node.

    • self: Object The semantic element used as the target of the node being rendered

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

  • defaultHeightExpression: InterpretedExpression Used to configure the default height of the node.

    • self: Object The semantic element used as the target of the node being rendered

    • editingContext: IEditingContext The editing context of the workbench. It can be used with core services to retrieve information about the semantic elements.

    • previousDiagram: Diagram The previously rendered diagram. It can be used to retrieve information about the previous state of the diagram and its elements.

    • diagramEvent: IDiagramEvent The current event that is involved in the refresh of the diagram.

4. Edge Description

EdgeDescription describes an edge and the way it is connected, styled, and labeled.

4.1. Core Properties

  • name: Identifier A unique identifier of the edge description. If the name is changed, existing edges created from this description will disappear and new edges will replace them. Existing handles, bendpoints and customizations done by the end users will be lost.

  • description: String Some documentation to let the studio makers understand the purpose of the edge description.

4.2. Rendering

  • sourceDescriptions: List<DiagramElementDescription> The list of node and edge descriptions to consider while computing the source of edges created from this description. Nodes or edges with a description in this list will be considered as potential source.

  • targetDescriptions: List<DiagramElementDescription> The list of node and edge descriptions to consider while computing the target of edges created from this description. Nodes or edges with a description in this list will be considered as potential targets.

  • isDomainBasedEdge: boolean Use false if the edge is used to represent a relation between model elements based on a reference or true if the relation itself is defined as a dedicated semantic element. For example in UML an association between two classes A and B is not represented by a reference from A to B but by an explicit Association model element which itself references both A and B. In this case, the edge description should be defined as a domain based edge using Association as its domainType.

While rendering edges, the cache: DiagramRenderingCache is available in order to query the current state of the diagram being rendered. This cache should be used to find the nodes that will appear in the new rendering of the diagram. Nodes are all rendered before edges.

4.2.1. Reference based edges

Here is the algorithm used to render reference based edges:

  • Use the DiagramRenderingCache to find all the nodes in the diagram that have been created from one of the source description.

  • Use a semantic element for the edge, the target of those nodes

  • For each semantic element, retrieve the diagram element displaying them matching the sourceDescriptions

  • Now that we have both the semanticEdgeSource and graphicalEdgeSource, we will evaluate the targetExpression to find the graphical targets of the edges to create matching the targetDescriptions

  • Now that we have the semanticEdgeTarget and the graphicalEdgeTarget, we will evaluate the preconditionExpression to figure out if the edge should be rendered

  • After that, we will leverage the synchronizationPolicy to find out if the edge should really appear in the diagram

  • Then we will render it by computing its labels, style, modifiers

The following properties are thus unused with reference based edges:

  • domainType: DomainType`

  • semanticCandidatesExpression: InterpretedExpression`

  • sourceExpression: InterpretedExpression`

Here are the properties to consider for reference based edges:

  • targetExpression: InterpretedExpression Used to find the target of the edges to create

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • semanticEdgeSource: Object

    • graphicalEdgeSource: Element

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

  • preconditionExpression: InterpretedExpression Used to figure out if an edge should be rendered or not

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • semanticEdgeSource: Object

    • semanticEdgeTarget: Object

    • graphicalEdgeSource: Element

    • graphicalEdgeTarget: Element

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

4.2.2. Domain based edges

Here is the algorithm used to render domain based edges:

  • Evaluate the semanticCandidatesExpression to find all the semantic elements to consider

  • Filter these results to only keep the semantic elements matching the domainType

  • Execute the sourceExpression to find the semantic elements to consider as semantic source of the edges

  • Find the diagram element used to display them matching the sourceDescriptions

  • Now that we have both the semanticEdgeSource and graphicalEdgeSource, we will evaluate the targetExpression to find the graphical targets of the edges to create matching the targetDescriptions

  • Now that we have the semanticEdgeTarget and the graphicalEdgeTarget, we will evaluate the preconditionExpression to figure out if the edge should be rendered

  • After that, we will leverage the synchronizationPolicy to find out if the edge should really appear in the diagram

  • Then we will render it by computing its labels, style, modifiers

Here are the properties to consider for domain based edges:

  • semanticCandidatesExpression: InterpretedExpression

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

  • domainType: DomainType

  • sourceExpression: InterpretedExpression

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

  • targetExpression: InterpretedExpression Used to find the target of the edges to create

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • semanticEdgeSource: Object

    • graphicalEdgeSource: Element

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

  • preconditionExpression: InterpretedExpression Used to figure out if an edge should be rendered or not

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • semanticEdgeSource: Object

    • semanticEdgeTarget: Object

    • graphicalEdgeSource: Element

    • graphicalEdgeTarget: Element

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

  • synchronizationPolicy: SynchronizationPolicy Used to configure how the edge created from this description will be synchronized with the semantic model. This is especially important when dealing with large models in which the semanticCandidatesExpression could return a very large number of elements. In order to prevent the creation of massive diagrams which are difficult to manipulate, one can use the synchronization policy to take control over the synchronization process. It can be configured to one of the following values:

    • SYNCHRONIZED The edge will be automatically created when if a semantic relation is found (reference or domain based). To delete the edge, the underlying semantic relation must not be reachable anymore (most of the time, when it has been deleted for example by removing a reference between two semantic elements).

    • UNSYNCHRONIZED The edge will not be automatically created when the semantic relation is found. Instead the edge will only be created if a tool explicitely asks for it. In this case, the edge can be deleted by another tool without deleting the underlying semantic relation. The edge will be automatically deleted if the underlying semantic relation is not reachable anymore.

4.3. Labels

An edge can have multiple labels which are computed thanks to dedicated expressions:

  • beginLabelExpression: InterpretedExpression Used to compute the label near the source of the edge.

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • semanticEdgeSource: Object

    • semanticEdgeTarget: Object

    • graphicalEdgeSource: Element

    • graphicalEdgeTarget: Element

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

  • centerLabelExpression: InterpretedExpression Used to compute the label in the middle of the edge.

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • semanticEdgeSource: Object

    • semanticEdgeTarget: Object

    • graphicalEdgeSource: Element

    • graphicalEdgeTarget: Element

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

  • endLabelExpression: InterpretedExpression Used to compute the label near the target of the edge.

    • self: Object

    • editingContext: IEditingContext

    • cache: DiagramRenderingCache

    • semanticEdgeSource: Object

    • semanticEdgeTarget: Object

    • graphicalEdgeSource: Element

    • graphicalEdgeTarget: Element

    • previousDiagram: Diagram

    • diagramEvent: IDiagramEvent

4.4. Styling

  • style: EdgeStyle

  • conditionalStyles: ConditionalEdgeStyle

4.5. Interaction

  • palette: EdgePalette Used to configure the palette of the edge. This palette is accessible thanks to a right click on an edge. It can contain tools to create new elements in the diagram or to perform actions on the edge.