-
Add specific Activity Documentation in user Doc Bug: https://github.com/PapyrusSirius/papyrus-web/issues/314 Bug: eclipse/papyrus/org.eclipse.papyrus-web#33 Signed-off-by:
Jessy Mallet <jessy.mallet@obeo.fr>
Add specific Activity Documentation in user Doc Bug: https://github.com/PapyrusSirius/papyrus-web/issues/314 Bug: eclipse/papyrus/org.eclipse.papyrus-web#33 Signed-off-by:
User Documentation
Home page
The home page is the starting point of a modeling project. It is where user can initiate a new project or manage an existing one.
Creating a new project in the platform can be done in the following ways:
-
Create a blank project
-
Create a project from existing templates
-
Upload a previously exported project
For more details on project creation topic, see Create a Project section of the documentation.
As far as existing projects are concerned, the following actions are available:
-
Open an existing project
To open an existing project, the user has to locate the project in the Project list and click on its name. -
Delete a project
See theDelete a Projectsection of the documentation -
Rename a project
See theRename a Projectsection of the documentation
Once the project (new or existing) is chosen, the workbench page is presented.
Workbench
The Workbench page is the main page where Projects are edited.
It is basically composed of one main central area and two side panels.
The left panel is mainly used to see the structure of the Project as a tree of all its parts.
The central area is the place where diagrams live and the right panel can display the Properties of the current diagram selection.
Project Explorer panel
The Explorer panel displays all elements contained by the Project. Root nodes are the Resources stored in the project where all elements underneath live. The root element for UML resources is generally a Model or a Profile.
Note that the name of the resource should always end with .uml.
|
Explorer Tree
To create a New Representation Diagram, use the contextual menu on any semantic element and choose the action New Representation, choose the type of diagram in the dialog.
The Explorer tree contains semantic elements of the Model and diagrams at the same level.
Diagram elements can be easily recognized by the diagram icon 
whereas semantic elements have specific icons depending on their nature.
From the Explorer view, it is possible to create new semantic elements. To do so, use the contextual menu on any semantic element and choose New Object. In the dialog, select the new element to create among all semantic elements listed in the dropdown (names are prefixed by the containment feature).
Regarding the representation creation, it is worth noting that Representations depend on the selected semantic element (the one used to open the contextual menu). Here are available representations and their creation contexts:
| Representation | Context |
|---|---|
Class Diagram |
Package |
Composite Structure Diagram |
Package |
Package |
Package |
Profile Diagram |
Profile or Package (in a |
State Machine Diagram |
State Machine |
Use Case Diagram |
Package |
As we can see in the table above, the State Machine Diagram can only be created on a State Machine semantic element.
Deletion of semantic elements (and representation diagrams) is possible through the contextual menu of tree nodes.
Explorer toolbar
The Explorer toolbar contains global Project actions:
-
Upload model
Add a previously downloaded UML Model into the Project. Accepted UML Model files should have the.umlextension -
Synchronization with Representation editor
When Synchronization with Representation is enabled, selecting a graphical element in the diagram will Reveal and Select the semantic element corresponding in the Explorer tree.
When Synchronization with Representation is disabled, selecting a graphical element in the diagram will Select the semantic element corresponding in the Explorer tree only if it has already been revealed.
Publish profile
Publish a profile in a dedicated database so it can be used by other projects. If the profile is already published, a new version is pushed to the database.
| Be aware that if a project already uses this profile it will not be notified that a new version is available until the project is unloaded which means that nobody has this project opened during 7 seconds. |
Validation panel
The Validation panel shares the left area of the workbench page with the Explorer. See the documentation section for more details.
Diagram panel
Generalities
The diagram panel shows Representation Diagrams created in the project. Several Representations can be opened and they appear in separate tabs.
Diagrams represent graphically a part of your semantic model. Each representation defines its own set of rules regarding its content.
Graphical elements can be selected by clicking on elements. The innermost clicked element is selected.
A red border (with eight square handles) appears around the element when it is selected.
Once a graphical element is selected, a second click on it will reveal a set of available tools grouped in a horizontal palette.
The Palette displays all the tools available according to the current selection. It has the following subgroups from left to right:
-
Children element creation group
All children’s creation actions are grouped in a dropdown list depending on the selected element’s nature. -
Generic tools (Edit, Delete from the diagram, Delete from the model, Hide, Fade) As far as Edit is concerned, it is worth noting that names (or more generally texts) can be edited in the following ways:
-
Edit action of the Palette
-
Press F2
As far as Edge elements are concerned, start and end labels can only be edited by double-clicking them. The above ways will edit the edge label itself (the centered label of the edge).
-
-
Collapse / Expand tools
Those actions are only available for containers or compartments (e.g Package or Operations Compartment of a Class)
The Diagram panel has global actions grouped in a horizontal toolbar underneath the diagram tabs.
This toolbar contains the following actions:
-
Display full screen
-
Fit screen action
-
Zoom group
-
Share the diagram link
-
Export diagram as SVG
-
Display Grid
-
Reveal hidden elements of action
-
Reveal faded elements of action
Label
Keywords on Nodes and Edges are displayed on the first separate line of the label. If the semantic element is stereotyped, the stereotype is displayed on a second separate line. Finally, the label will be displayed on the third line. The label can be the simple name of the element, or more complex in some specific cases detailed in the corresponding diagram section. Label of UML elements with the isAbstract feature set to true is displayed in italic. Label of UML elements with the isStatic feature set to true is displayed underlined.
Edge Creation
Edges can be created between Nodes whose types match the Edge’s source and target types. If the creation of an Edge is not authorized, the target node appears faded. When user try to create an edge, he clicks first on the source element to display arrow. Then he clicks on one of these arrows and stay click until the target. User can see the feedback of the edge and the target node is highlighted. It is not possible for now to create an Edge between two Edges or between an Edge and a Node.
Semantic Drag&Drop
Users can select elements in the Explorer view and drag and drop them into their container Nodes in the diagram. This drag and drop doesn’t perform any semantic modification, except in specific case detailed in the corresponding diagram section. In addition, some diagrams allow semantic drag and drop of any element from the Explorer view (in the same resourceSet as the diagram) on the background of the diagram.
Dragging and dropping an element represented as an Edge on the diagram will create the source/target elements of the Edge if they aren’t already represented. Note that Edges can be dropped anywhere on the diagram, but they will only appear in their semantic container.
Activity Diagram
Activity diagrams help to focus on workflows. They are therefore particularly suitable for modeling control flows and data flows. They allow to graphically represent the behavior of a method or the course of a use case.
Specific Features on Creation
-
When creating an ActivityPartition in an Activity, the partition is added in the Activity#partition feature of the Activity. This feature is a subset of the Activity#OwnedGroup containment feature.
-
An AcceptEventAction is represented with an hourglass when it has exactly one Trigger that references a TimeEvent in its Trigger#event feature.
Specific Features on Pin
-
The Pin creation tool is deactivated if several containment features are possible to own the Pin.
-
On an UML element, if the feature multiplicity is [0..1] or [1..1] or [1..*], a Pin is created at the same time as the element creation.
-
The Pin name is set with the name of the feature, if the feature is [0..1] or [1..1].
Specific Features on Container
Some containers do not contain semantically their graphical nodes. This is the case for ActivityPartition and InterruptibleActivityRegion. ActivityNodes contained in those containers are owned by the first parent Activity.
Specific Features on DecisionNode
A note attached to the DecisionNode is displayed when the DecisionNode#decisionInput feature is set. This note only appears if the DecisionNode node is displayed.
Specific Features on Direct Edit
-
The direct edit tool doesn’t perform any modification on the root Activity nor Constraint/Comment Links.
Communication Diagram
The communication diagram is a graphical description used to represent the methods of communication between objects. Communication diagrams are simplified representations of sequence diagrams focused on specific messages exchanged by lifelines. Note that these diagrams aren’t intended to represent data manipulation involved in these transactions.
Specific Features on Label
-
The label of a Lifeline representing a Property is the name of the Property instead of the Lifeline name.
Specific Features on Direct Edit
-
The direct edit tool doesn’t perform any modification on the root Interaction nor Constraint/Comment Links.
Specific Features on Deletion
-
The semantic and graphical deletion tools don’t perform any deletion on the root Interaction.
Specific Features on Edge creation
-
Messages can only be created between Lifelines and the Message orientation is displayed with an arrow on the target side of the edge.
Specific Features on Graphical Drag&Drop
-
No graphical drop is authorized on this diagram because there is no container node.
Specific Features on Semantic Drag&Drop
-
A Type can be drag and dropped on the root Interaction of the diagram. This creates a new semantic Property typed with the dropped Type. A Lifeline is also semantically created, representing the new Property (through its represents reference). Finally, the node representing the Lifeline is created on the root Interaction of the diagram.
-
A Property can be drag and dropped on a Lifeline node. The Lifeline now represents this Property (through its represents reference).
-
A Type can be drag and dropped on a Lifeline node. This creates a new semantic Property typed with the dropped Type. A Lifeline is also semantically created, representing the new Property (through its represents reference).
Portal representation
A portal can be created anywhere (on any semantic element in the project) and is just a kind of dashboard where the end-user can add other representations (of any kind) so that they can be all opened at the same time.
See Portal Documentation for more details.
Profile Diagram
The Profile diagram provide a way to extend an UML model. They are based on additional stereotypes (identified as classes with the «stereotype» stereotype) and labeled values that are applied to UML element thanks to the extension relation.
Specific Features on Label
-
The label of an ElementImport is the label of the UML metaclass it references as its imported element.
Specific Features on Direct Edit
-
The direct edit tool doesn’t perform any modification on UML metaclasses, Generalization and Link (from Constraint or Comment).
Specific Features on Semantic Drag&Drop
-
The semantic drag and drop of an ElementImport with an UML metaclass as its imported element on the Profile diagram produces a Node with the name of the UML metaclass as its label. Note that it is not possible to drag and drop ElementImport with no imported element or with an imported element that is not an UML metaclass.
UseCase Diagram
The UseCase diagram is a graphical description used to represent the different ways a user can interact with a system. Use case diagrams show the functional elements (use cases represented by ellipses), the individuals or objects that invoke these functionalities (actors shown as stick figures), and possibly the elements responsible for implementing these use cases (subjects).
Right side panel
On the right of the page, one can see several stacked views giving information about the current selection.
Details
The Details panel is used to visualize and edit all the features of the selected semantic object (from Explorer or diagrams). The panel is divided into 4 separate tabs:
-
UML: details the main UML features of the semantic element
-
Comments: displays comments associated with the selected element. Those comments can be owned by the element or applied to it (using a relation between the comment and this element).
-
Profile: focus on applied stereotypes/profiles of this selected element
-
Advanced: This tab displays all features of the semantic element. It uses generic rules to find the best suitable widget to visualize and edit the feature.
In the UML tab, each property is represented by an appropriated widget according to its nature. For instance, a property of type ecore::EString will be represented by a text widget. It might be, in some situations more appropriate to represent this string with a text area widget that supports multiple lines of text.
UML panel
Basic widgets
In the following table, we present the mapping between basic types and their associated widgets
| Basic Type | Widget |
|---|---|
Mono Boolean |
Checkbox |
Mono String |
Text field or Text area |
Mono Number |
Text field |
Mono Enumeration |
Select or Radio |
Many Boolean, String, Number, Enumeration |
Primitive List |
Many and Mono Reference |
Reference |
Here is the Sirius documentation of all those widgets.
Beside these standard widgets, some UML 2 concepts have properties that need a special UI to manage their data. The following sections detail of each custom widget we introduced.
Language Expression
A language expression custom widget has been introduced to manage a couple of connected lists in the following concepts:
-
FunctionBehavior -
OpaqueAction -
OpaqueBehavior -
OpaqueExpression
All those concepts manage a couple of lists of strings which are weakly connected via their index. The first list, called 'languages' contains the name of languages, such as "JAVA" or "C++". The second one contains the body expression expressed in the language of the same rank in the list. Thus those lists could not be edited in Papyrus UI as separate ordinary lists of text fields. This is the reason why a new custom widget has been developed.
The above image shows the custom widget associated with the virtual property 'language' of a FunctionBehavior. The plus icon in front of the property label can be used to populate the following list by adding a predefined language or a new one. This selection of the language to add is done using a modal dialog.
Each language in the list is shown as a collapsible section with the name of the language as the title. On the right part of the header/title section, there is the section toolbar containing all actions that can be performed in this language. Once a language is expanded, the body of the language is revealed and the user can modify it. Only one language is expanded at a time. An expanded language will be automatically collapsed if the user expands another one.
Languages can be reordered using up or down actions of the toolbar. Since the list is not a ring, the user is not allowed to move up the first language or move down the last one.
Removing a language can be done using the trash icon action of its toolbar. No confirmation is required before deleting a language element.
Primitive List
The primitive list custom widget aims to provide capabilities to visualize and edit EAttributes which represent more than one value.
The values are represented as list items. Each item can be deleted using the trash icon. To add a value, the New item input can be used. Be aware that the server receives a String value and needs to convert it to the correct DataType. For widgets used in the default pages of the Details view, Papyrus Web uses pure EMF implementation to convert the given String into the required DataType. It is also possible provide a strict list of candidates for enumeration or boolean, for example. In that case, the list of possible values are presented in a dropdown whereas the text field is used as a filter of those values. This list of possible values is requested to the back end only when it is necessary (when the dropdown menu is presented). In case of a displayExpression is specified in the PrimitiveList widget, this expression is evaluated for each candidate. Inside this expression, the AQL variable candidate can be used to refer the current candidate value. Once the user chooses the value, it may be added using the plus icon action. For example, for a boolean feature, there are only two value allowed true and false.
In the context of UML, for a more exhaustive list of conversion rule look at:
-
org.eclipse.uml2.uml.internal.impl.UMLFactoryImpl.createFromString(EDataType, String)
-
org.eclipse.uml2.types.internal.impl.TypesFactoryImpl.createFromString(EDataType, String)
The primitive list has also the capability to reorder its items. This is an optional capability that is controlled by the presence of an expression inside the view model of the widget. If such an expression is provided an reorder icon appears on the left of the list title as displayed below:
Triggering this reorder icon opens a dialog in which the user can change the order of the list items:
The primitive list custom widget can be configured to have a single extra action on each item. This item action is optional and can be deactivated using the PrimitiveListItemActionOperation.preconditionExpression. One can control the UI appearance of the action by setting its icon file.
As an example, the following image shows a paperclip icon for the item action and when the user clicks an information pops up with the clicked item name.
References
Depending on the nature of the reference, we handle it differently. Containment references use a dedicated custom widget, while non-containment references use Sirius components reference widgets.
Containment reference widget
In those references, reference values are child nodes of the reference owner, which means that the elements referenced in the widget can be found underneath the reference owner.
For instance, a class that has two operations set in its Owned Operations property can be found as children nodes of the Class node in the Model Explorer
The containment reference widget has the following actions available:
-
The plus icon to change the reference value
It starts to create a new child element. If the specified type of the reference has derived types, a modal dialog is open to choose the actual type of the new element. After its creation, the new element is set as the reference value in case this reference is a mono-valued one, or added to the reference value list otherwise.
|
In case of mono-valued containment reference, if the value is already set, the user is not allowed to create a new element and the plus icon is disabled. In this situation, the user has to remove first the current value before creating a new one. |
-
The reorder icon to sort the reference values (optional: only for multi-valued references).
Reordering values can be done manually inside a dedicated dialog:
-
The cross icon on each value element to remove this value in the reference and delete the element from the model.
-
Clicking value elements inside the reference navigates to those elements.
Non-containment reference widget
Non-containment references are managed using the Sirius components reference widget.
Actions available in non-containment reference widgets are:
-
Ellipsis icon to set/edit the value of the reference using a dialog:
In a mono-valued reference, the user can select a compatible element to set in the reference (this element will possibly replace the current reference value)
Whereas in a multi-valued reference, the dialog allows the user to manage the list of reference values. The left panel contains compatible elements within the editing context. Elements displayed with a bold label are elements that are currently present in the reference value list. This list can be seen in the right panel. Icons in between those panels can be used to move a selected element from right to left (remove operation) or from left to right (add operation). Moving elements can also be performed by dragging an element from a panel and dropping it to the other one. Finally, current elements (in the right panel) can be reordered using drag and drop.
-
The plus icon to create a new element and change the reference value.
Since new element is not contained by the reference owner, user has to first specify the new element’s container and the actual type of element to create. This is done inside the create dialog:
For a mono-value reference, once the new element is created it is set as the reference value and replaces its current value. In case of a multi-valued reference, the new element is added at the end of the value list.
-
The trash icon to clear the reference value.
-
The dropdown icon to choose a value among compatible elements (not already present in the reference value) found in the editing context.
For a mono-valued reference the selected value replace the existing one, whereas it is added to the value list in case of multi-valued. -
The user can type some text in the values area to filter dropdown list content.
-
Each value element has a cross icon to remove it from the reference.
Since this is a non-containment reference, the removed element is only removed from its value and the referenced element still exists in the model.
|
In some widgets the following warning message will be displayed when trying to remove an element using the cross button.
The element is not removed from the list. This security prevents you to remove the element because this would cause the deletion of the current selected item. In most case, the currently edited reference is an eOpposite of the reference that is currenlty containing the displayed element. This is the case for the widget Context on a Constraint. |
-
Clicking value elements inside the reference navigates to those elements.
Rule for searching candidate values of non-containment reference
As we have seen in previous sections, the dialogs to set (or edit) value references and the dropdown collect all possible compatible values for a reference. This is done with a dedicated UML domain service. This service is in charge of finding all reachable elements from the element owing the reference that are compatible with the type of the reference. The following algorithm is used to perform this search:
-
Starting from the element owning the reference, all elements of the current model are reachable.
-
PackageImport elements found in between the element itself and the root of the model are collected.
-
All imported packages of those PackageImport elements and their content are reachable.
-
The previous steps are recursively applied for each imported package.
|
Since the above search rule is using PackageImport element and its |
|
In some case, the following warning message will be displayed:
Or
when creating a new element using the + button. For most cases, it is caused by an incompatible type in an eOpposite feature. It means that the selected type is valid for editing the current reference but it has an eOpposite reference that cannot contain the current element. This is mostly caused by the use of reference type redifinition in the UML metamodel (look for "redefine" EAnnotations). For example, this is the case when creating an Activity in widget Owned parameter element on TemplateParameter concept. |
Definition panel
When a Profile element is selected (for instance inside the Explorer), the definition tab is shown in the Details panel. The Definition page contains all profile’s version detailed information. These information are those typed inside the dialog each time the profile is published.
All profile definitions are stacked together with the more recent version on top of the panel.
Each profile definition can be removed using the trash button.
| The remove action only remove the profile definition from the model. It does not "unpublish" the profile. |
Comments panel
As we have already mentioned, Comments panel displays for the selected element the list of owned and applied comments. Applied comments contains the list of Comments that are currently annotating the selected element.
The feature Annotated Element of the related Comment element contains the select element.
Both features, Applied comments and Annotated element work together and are in-sync. That means that adding (or removing) an element in Annotated element of a Comment automatically adds (or removes) this comment to the Applied comments of the element and vice-versa. Creating a new Comment from the Applied comments list of selected element has two actions:
-
first a new Comment is created somewhere (as defined in the Creation dialog)
-
next, the selected element is added inside the Annotated element of this new comment to ensure that these relations are in-sync.
Profile Panel
On an Element selection, the Applied Stereotype widget provides the capacities to:
-
Apply a stereotype: Use the dropdown or start entering the name of the Stereotype.
-
Unapply a stereotype: Use the trash icon next to the Stereotype item.
If a Package is selected, the Applied profiles widget provides the capacities to:
-
Apply a profile: Use the dropdown or start entering the name of the Profile.
-
Unapply a profile: Use the trash icon next to the Profile item.
-
Update a profile: If a newer version of the profile is available, use the refresh button next to the Profile item.
Stereotype panels
For each stereotype applied on a specific element, a dedicated tab on the Details panel can be open when this element is selected. This tab contains all the features provided by the corresponding stereotype for this element. According to the kind of each feature, a specific widget is used to handle this feature. In the following tables, we are presenting all kind of supported features and the associated widget to handle it in the panel.
Attributes
Feature kind |
Widget |
String |
TextArea |
Boolean |
Checkbox |
Boolean Object |
Primitive Radio |
int or Integer |
Textfield |
float or Float |
Textfield |
double or Double |
Textfield |
Enumeration |
Select |
Feature kind |
Widget |
List of String |
Primitive List |
List of Boolean |
Primitive List |
List of Boolean Object |
Primitive List |
List of int or Integer |
Primitive List |
List of float or Float |
Primitive List |
List of double or Double |
Primitive List |
List of Enumeration |
Primitive List |
Related Elements
There is a section about the Related Elements view in the documentation.
Representations
There is a section about Representations view in the documentation.