diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 21d3b6d9e3..c2808de359 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -5,6 +5,7 @@ === Shapes - Add support for text alignment on labels +- Add support for gantt representation === Architectural decision records @@ -102,6 +103,7 @@ image:doc/screenshots/insideLabelPositions.png[Inside label positions, 70%] - https://github.com/eclipse-sirius/sirius-web/issues/3606[#3606] [test] Improve error handling in ExecuteEditingContextFunctionRunner and ExecuteEditingContextFunctionEventHandler - https://github.com/eclipse-sirius/sirius-web/issues/3561[#3561] [diagram] Add support for background and border on diagram labels - https://github.com/eclipse-sirius/sirius-web/issues/3604[#3604] [diagram] Make node overlap resolution faster during "Arrange All" +- https://github.com/eclipse-sirius/sirius-web/issues/3653[#3653] [gantt] Add documentation for gantt representation == v2024.5.0 diff --git a/doc/specifier/images/gantt-description-overview.png b/doc/specifier/images/gantt-description-overview.png new file mode 100644 index 0000000000..5a6b61304c Binary files /dev/null and b/doc/specifier/images/gantt-description-overview.png differ diff --git a/doc/specifier/images/gantt-overview.png b/doc/specifier/images/gantt-overview.png new file mode 100644 index 0000000000..f4307da1ea Binary files /dev/null and b/doc/specifier/images/gantt-overview.png differ diff --git a/doc/specifier/images/gantt-task-handlers.png b/doc/specifier/images/gantt-task-handlers.png new file mode 100644 index 0000000000..c48bbcbdd9 Binary files /dev/null and b/doc/specifier/images/gantt-task-handlers.png differ diff --git a/doc/specifier/images/gantt-task-relation-tool.png b/doc/specifier/images/gantt-task-relation-tool.png new file mode 100644 index 0000000000..51157153b4 Binary files /dev/null and b/doc/specifier/images/gantt-task-relation-tool.png differ diff --git a/doc/specifier/images/gantt-task-tools.png b/doc/specifier/images/gantt-task-tools.png new file mode 100644 index 0000000000..05ffc67bc2 Binary files /dev/null and b/doc/specifier/images/gantt-task-tools.png differ diff --git a/doc/specifier/images/gantt-tools.png b/doc/specifier/images/gantt-tools.png new file mode 100644 index 0000000000..34eb1541c8 Binary files /dev/null and b/doc/specifier/images/gantt-tools.png differ diff --git a/doc/specifier/representation-gantt.adoc b/doc/specifier/representation-gantt.adoc new file mode 100644 index 0000000000..7d2e578f04 --- /dev/null +++ b/doc/specifier/representation-gantt.adoc @@ -0,0 +1,127 @@ +# Gantt representation description + +This chapter explains how to configure a `Gantt` representation in the `View` model. + +A `Gantt` representation is made of a hierarchy tasks. + +* A task can contain sub-tasks. +* A task can be linked to another task with a dependency relation. + +Each `Task` is associated with a semantic element that is an object of the model. + +image::images/gantt-overview.png[Gantt representation overview] + +## Gantt description + +To define how your model is represented with a `Gantt` representation, the specifier needs to create a `GanttDescription` in the `View` model. + +image::images/gantt-description-overview.png[Gantt description overview] + +* `Name`: A name that helps the specifier to know what the GanttDescription is about +* `Domain Type`: Type of the object on which it is possible to create the representation +* `Precondition Expression`: An expression that determines if it is possible to create the representation +** `self` variable is the semantic element associated with the `Gantt`. +* `Title Expression`: The initial name of the representation once created +** `self` variable is the semantic element associated with the `Gantt`. +* `Date Rounding Expression`: An expression that returns a string that is a time duration that will define how the date is rounded when changing the date from the Gantt representation. +The string contains +** an integer which is the number of time unit. +** a character among {D,H,m} corresponding to a Day, Hour or minute time unit. +Example: to round to half a day, the expression must returns `12H` + +## Task description + +The `TaskDescription` is used to define the direct tasks of its parent in the tasks hierarchy. +It can be the root tasks in the Gantt or the sub-tasks in a task. + +* `Name`: A name that helps the specifier to know what the TaskDescription is about +* `Semantic Candidates Expression`: An expression that returns one or more semantic elements. +Each semantic element will be represented by a task. +** `self` variable is the semantic element associated with the `Gantt`. +* `Domain Type`: Type of the object used to filter the semantic object represented by a task + +All the following expressions are called as many times as the number of semantic elements returned by the `Semantic Candidates Expression`. +`self` variable is the current semantic element. + +* `Name Expression`: An expression that defines the name of the task +* `Description Expression`: An expression that defines the description of the task +* `Start Time Expression`: An expression that returns a `java.time.Instant` to define the start date of the task. +* `End Time Expression`: An expression that returns a `java.time.Instant` to define the end date of the task. +* `Progress Expression`: An expression that returns an integer between 0 and 100 to define the percentage progress of the task. +* `Compute Start End Dynamically Expression`: An expression that returns a boolean. +If true and if the task contains sub-tasks, the start and end dates displayed in the Gantt are computed from the sub-tasks. +The start date(respectively the end date) is the lower(respectively upper) date of the sub-tasks dates. +* `Task Dependencies Expression`: An expression that returns a list of semantic elements to define dependency relations between the current task and the tasks associated the returned semantic elements. + +### Task description as sub task + +To define tasks as the second level of the tasks hierarchy, create a `TaskDescription` in the `TaskDescription`. + +It is also possible to reuse `TaskDescription` so that it is possible to define a recursive definition. +Use `Reused Task Element Descriptions` field to select existing `TaskDescription`. + +## Tools + +Many tools can be configured for `Task`. +All the tools are created under `GanttDescription`. +Note that, by default, a tool does nothing. +You need to add operations in the tool to make changes in the semantic model. +Typical operations: + +* `Change Context`: It allows to change the `self` value. +But typically this operation is useful if you just want to call a java service that will implement the tool behavior. +* `Create Instance`: Creates a semantic object and add it in the defined feature of the `self` semantic element +* `Set Value`: Sets the value on a given feature on `self` semantic element +* `Delete Element` +* etc + +Each tool gives access to variables that can be used in the expression of the tools. +When the tool is executed, the system will set the variables(that depends on the execution context of the tool) and executes the operations associated with the tool. + +image::images/gantt-tools.png[Gantt tools] + +### Task tools + +* `Create Task Tool`: This tool defines the behavior when the user creates a task using the button in the task contextual palette in Gantt. +Available variables: +** `self`: The semantic element associated with the selected Task +* `Delete Task Tool`: This tool defines the behavior when the user deletes a task using the button in the task contextual palette in Gantt. +Available variables: +** `self`: The semantic element associated with the selected Task + +image::images/gantt-task-tools.png[Task palette tools] + + +* `Edit Task Tool`: This tool defines the behavior when the user uses the handles to change start or end dates or the progress. +Available variables: +** `self`: The semantic element associated with the selected task. +** `newName`: The new value of the name. +** `newStartTime`: The new value of the start time. +** `newEndTime`: The new value of the end time. +** `newDescription`: The new value of the description. +** `newProgress`: The new value of the progress. + +image::images/gantt-task-handlers.png[Task handlers] + + +* `Drop Task Tool`: +This tool defines the behavior when dragging and dropping, in the table part of Gantt, a task before, after or inside another task. +Available variables: +** `sourceObject`: The semantic element associated with the dragged task +** `targetObject`: The semantic element associated with the target task where the task is dropped. +** `sourceTask`: The dragged `Task`. +** `targetTaskOrGantt`: The target where the task is dropped. +It can be `Gantt` or another `Task`. +** `indexInTarget`: The index of the dropped task inside the new list of tasks where it is dropped. +index=0 means first position. + +### Dependency tools + +* `Create Task Dependency Tool`: +This tool defines the behavior when creating a task dependency by dragging the dependency handler from one task to another. +Available variables: +** `sourceObject`: The semantic element associated with the task from which the dependency link is initiated. +** `targetObject`: The semantic element associated with the target task where the dependency finishes. + +image::images/gantt-task-relation-tool.png[Create Task Dependency Tool] + diff --git a/doc/user/images/gantt-overview.png b/doc/user/images/gantt-overview.png new file mode 100644 index 0000000000..f4307da1ea Binary files /dev/null and b/doc/user/images/gantt-overview.png differ diff --git a/doc/user/images/gantt-task-dependencies.png b/doc/user/images/gantt-task-dependencies.png new file mode 100644 index 0000000000..40ca477d2d Binary files /dev/null and b/doc/user/images/gantt-task-dependencies.png differ diff --git a/doc/user/images/gantt-task-dependency-tool.png b/doc/user/images/gantt-task-dependency-tool.png new file mode 100644 index 0000000000..51157153b4 Binary files /dev/null and b/doc/user/images/gantt-task-dependency-tool.png differ diff --git a/doc/user/images/gantt-task-dependency.png b/doc/user/images/gantt-task-dependency.png new file mode 100644 index 0000000000..24906ae018 Binary files /dev/null and b/doc/user/images/gantt-task-dependency.png differ diff --git a/doc/user/images/gantt-task-dragdrop.png b/doc/user/images/gantt-task-dragdrop.png new file mode 100644 index 0000000000..d72b541a53 Binary files /dev/null and b/doc/user/images/gantt-task-dragdrop.png differ diff --git a/doc/user/images/gantt-task-group.png b/doc/user/images/gantt-task-group.png new file mode 100644 index 0000000000..553ebc9135 Binary files /dev/null and b/doc/user/images/gantt-task-group.png differ diff --git a/doc/user/images/gantt-task-handlers.png b/doc/user/images/gantt-task-handlers.png new file mode 100644 index 0000000000..c48bbcbdd9 Binary files /dev/null and b/doc/user/images/gantt-task-handlers.png differ diff --git a/doc/user/images/gantt-task-milestone.png b/doc/user/images/gantt-task-milestone.png new file mode 100644 index 0000000000..6345c69508 Binary files /dev/null and b/doc/user/images/gantt-task-milestone.png differ diff --git a/doc/user/images/gantt-task.png b/doc/user/images/gantt-task.png new file mode 100644 index 0000000000..fb5051b983 Binary files /dev/null and b/doc/user/images/gantt-task.png differ diff --git a/doc/user/images/gantt-toolbar.png b/doc/user/images/gantt-toolbar.png new file mode 100644 index 0000000000..6381345efe Binary files /dev/null and b/doc/user/images/gantt-toolbar.png differ diff --git a/doc/user/representation-gantt.adoc b/doc/user/representation-gantt.adoc new file mode 100644 index 0000000000..12194582cb --- /dev/null +++ b/doc/user/representation-gantt.adoc @@ -0,0 +1,108 @@ +# Gantt representation + +A `Gantt` representation is made of a hierarchy tasks. +Each task can contain sub-tasks. + +The left part is a table. +Each row represents a task. +The columns of the table provide information about the task. + +The right part is the Gantt itself. +Each row displays a task. +A task can be linked to another task with an arrow to represent a dependency relation. + +image::images/gantt-overview.png[Gantt representation overview] + +## Gantt display + +There are 3 types of task: + +* The basic task + +image::images/gantt-task.png[Gantt task] +A color shows the progress value of the task. +Fully colored mean 100%. + +* The group task that is a task which contains sub-tasks + +image::images/gantt-task-group.png[Gantt group] +A color shows the progress value of the task in the bottom part. +Depending on how the `TaskDescription` is configured in the `View` model, the task group may be either *computed from its sub-tasks* or defined independently as a basic task. +In the former case, the start(respectively end) date is the minimal start(respectively maximal end) date of the sub-tasks and the progress is a weighted average of the sub-tasks progress. + +* The milestone represents a date. + +image::images/gantt-task-milestone.png[Gantt milestone] + +A task can have a list of dependencies to other tasks. +The dependencies are represented by an arrow between two tasks oriented from the dependency to the dependant task. + +image:images/gantt-task-dependencies.png[Task Dependencies] + +## Gantt Toolbar + +image::images/gantt-toolbar.png[Gantt Toolbar] + +* `Toggle full screen mode`: It allows to display the representation in full screen +* `Zoom level`: Choose the time unit in the Gantt (Hour, Half Day, Day, Two Days, Week, Month, Year) +* `Zoom in` +* `Zoom out` +* `Fit to screen`: Set the zoom level that allows to display all the tasks +* `Display columns`: Allow to hide all the columns in a click. +Using the drop down combo, the user chooses the displayed columns. +The displayed columns are persisted in the Gantt representation. +* `Share`: Provide an URL that reaches directly the current Gantt representation + +## Selection + +When selecting a `Task` in Gantt or in the Table, the associated semantic element is selected in the `Explorer` and its properties are displayed in `Details`. + +## Edition + +### Task attributes + +Using handlers on the task, it is possible to change the start/end dates and the progress. +Clicking on the task and moving it left or right, allows to shift the date keeping the same duration. + +image:images/gantt-task-handlers.png[Show/Hide Cards] + +When changing a date, the date is rounded accordingly to the `Date Rounding Expression` define in the `GanttDescription`. +Holiday is set as Saturday and Sunday. If the rounded date is part of the holiday, it is moved to the next or previous working date. +Note that a date rounded greater than two days is not adjusted to the working days. + +### Task dependency relation + +Using the round handler next the task allows to create a dependency relation. + +image:images/gantt-task-dependency-tool.png[Task Dependency Tool] +image:images/gantt-task-dependency.png[Task Dependency] + + +### Task reordering + +From the table, it is possible to drag and drop a Task to reorder the task or change its container. + +image:images/gantt-task-dragdrop.png[Task Drag and Drop] + +* To reorder, drop the task before or after another. +* To change its container, drop the task on another task. + +Note that it is not possible to drop a task in its own children hierarchy. + + +## Table + +The table is made of rows and columns. +There is one row per task. + +The first column presents the hierarchy of tasks. +It shows the name of the task and optionally an icon to expand/collapse the sub-tasks. +The *expand status is persisted* in the Gantt representation. + +The other columns display the start/end dates and the progress. + +The columns can be resized and *the column width is persisted* in the Gantt representation. +From the Gantt toolbar, the columns can be hidden (See 'Gantt toolbar' section). + + +