diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 5c43049411..d9994c2d42 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -12,6 +12,7 @@ - Add impact analysis before tool execution - Add support for artifact publication from a project - Improve image export +- Add project elements selection to URLs === Architectural decision records diff --git a/doc/iterations/2025.2/add_project_elements_selection_to_urls.adoc b/doc/iterations/2025.2/add_project_elements_selection_to_urls.adoc new file mode 100644 index 0000000000..eb812f684c --- /dev/null +++ b/doc/iterations/2025.2/add_project_elements_selection_to_urls.adoc @@ -0,0 +1,89 @@ += (M) Add project elements selection to URLs + +== Problem + +Currently, Sirius Web has URLs for projects `+https://example.org/projects/project-id/edit+` and their representations `+https://example.org/projects/project-id/edit/representation-id+`. + +But there are no URLs that can be used to designate a selection of *project elements* (_models_ and/or _representations_ and/or _semantic elements_). +This possibility would be useful for documentation and collaboration purposes. + +== Key Result + +End users shall be able to create links that include a selection of project elements. + +=== Acceptance Criteria + +- End users can easily obtain a URL from their current selection of project elements in the workbench. +- When resolving a URL that specifies a selection, the specified project elements automatically get selected in the workbench. + +== Solution + +- The current URL will change based on the selection made in the workbench. +- The identifiers of the selected project elements will be stored in the URL in parameter _selection_. +- The order of the project element identifiers in the URL reflects the order of the project elements in the selection. +- A project element may appear several times in the selection. + This is for instance the case if several different graphical elements in a representation represent the same semantic element. +- Upon resolving a URL with parameter _selection_, the workbench selection is set to the specified project elements. +The resulting behavior may depend largely on how the workbench and its sections decide to implement this behavior. +- In the default workbench, the selection will be dispatched to the _Representation Editor_ (if opened), or otherwise to the _Explorer_ view. +- In both the _Explorer_ view and the _Representation Editor_, selecting a semantic element means selecting all the graphical elements whose _target_ is that semantic element. +In particular, this means there may be a lot of graphical elements that end up selected, because representations may include any number of graphical elements to represent a single semantic element. + +=== Scenario 1 : Obtaining the URL from a workbench selection + +- The end user is in a project. +- If no representation is opened, the URL looks like `+https://example.org/projects/project-id/edit+`. +- If a representation is opened, the URL looks like `+https://example.org/projects/project-id/edit/representation-id+`. + +The following behavior is the same in both cases. + +- The end user selects project elements. +This can be done through any section of the workbench that supports selections: _Explorer_ view, _Representation Editor_, _Related Elements_ view, etc. + +- The selected elements can be: +-- _Models_, e.g. the root elements in the _Explorer_ view. +-- _Representations_, e.g. the _Explorer_ view displays them below their target element. +-- _Semantic elements_, contained by a _model_ or a _semantic element_. +-- _Graphical elements_, i.e. part of a representation. +In that case, the intention is to capture in the selection their target semantic elements. + +- Upon selecting an element in the workbench, its corresponding project element identifier is retrieved, e.g. `+id_1+`. +- The URL gets updated automatically in order to reflect the selection change, into either: +-- `+https://example.org/projects/project-id/edit?selection=id_1+` +-- `+https://example.org/projects/project-id/edit/representation-id?selection=id_1+` +- Upon selecting another element in the workbench, its corresponding project element identifier is retrieved and appended to the _selection_ parameter, which means the URL is updated to either: +-- `+https://example.org/projects/project-id/edit?selection=id_1&id_2+` +-- `+https://example.org/projects/project-id/edit/representation-id?selection=id_1&id_2+` +- If selecting two graphical elements representing the same target semantic element, the following URLs are also possible: +-- `+https://example.org/projects/project-id/edit?selection=id_1&id_1+` +-- `+https://example.org/projects/project-id/edit/representation-id?selection=id_1&id_1+` + +=== Scenario 2 : Resolution of a URL containing the selection parameter + +- The URL path, whether it is a project or representation URL, is resolved as usual. + This means the specified project is opened, and if a representation is specified, it is opened in the representation editor. + +- The identifiers specified in the _selection_ parameter of the URL query are retrieved. + Based on these identifiers, we are able to retrieve the project elements that are meant to be selected. + +- The workbench selection is set to those elements. + +- The selection is revealed in the workbench. + +=== Breadboarding + +N/A + +=== Cutting backs + +N/A + +== Rabbit holes + +- When setting up the workbench selection programmatically, we have to make sure that as a result of the selection changing, the URL does not get updated automatically. +We do not want the selection and/or the URL to flicker. +- Project element identifiers are rather long so our URLs might end up being very long. We may need to encode the selection in order to make it shorter. + +== No-gos + +N/A