[doc] Add shape for supporting selections in URLs #4436
Conversation
| - 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. |
There was a problem hiding this comment.
I would disagree that it is a feature of the solution, it's just a very minor bug that does not produce any value. If the multiple selection in a diagram is producing such state, it's a bug not a feature to advertise.
| - 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. |
There was a problem hiding this comment.
I disagree, there may be a bug today that would make multiple nodes associated with the same semantic element create a selection with the same id multiple times but it's a bug not a feature that we want as part of the solution. I don't think we need anything special to prevent it but I would not advertise it as a feature either.
| - 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. |
There was a problem hiding this comment.
There's not decision to be made or guessed here, the behavior is explicit. Sirius Web is in charge of both the URL and the selection, it uses the Sirius Components Workbench to display stuff and the SelectionContext to manage the selection. The selection context holds a state and that's it, nothing more. When it is updated, all the components which are subscribed to this state will have the new selection (it includes the workbench).
If the new selection contains ids that are recognized by the backend as representation metadata, they are displayed as tabs of the workbench. If the selection is used by a representation then this representation updates its content to show this 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. |
There was a problem hiding this comment.
It doesn't really work this way in terms of responsibility, it's not really dispatched as in the Workbench does not know or choose anything with the selection and its propagation. Components are choosing to subscribe to the selection, the workbench does not care about anything specific opened like the explorer view or any other view, its doesn't even depend on them. There's no reason to mention special use cases specific to representations in this ADR, its scope is the workbench as a whole.
This shape is about EditProjectView and its usage of SelectionContextProvider and Workbench not about specific representations
| - 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. |
There was a problem hiding this comment.
No, that's just one part of the behavior it's not the case in all representations and not even in all use cases of existing representations of Sirius Components. It is sometime the case in some scenarios but it's not a behavior set in stone.
| - 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. |
There was a problem hiding this comment.
Technically we don't know, on purpose, what a selected element is. It's not limited to those four use cases, we just don't know nor care.
| -- `+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+` |
There was a problem hiding this comment.
THIS is the most important part of the shape but the format ?key=value&xxxx is used as part of the standard to parse URL, you will end up creating conflicts in the way the URL is interpreted. This example doesn't work as is. There are two main options available:
- https://example.org/projects/{projectId}/edit?selection=a&selection=b&selection=c
- the default behavior in HTML to encode multiple values in the URL, you need to mention it
- https://example.org/projects/{projectId}/edit?selection=1%2C2%2C3%2C4
- with
%2Cbeing the encoded version of,(the alternate way supported by Spring MVC for example)
- with
Given that the former is more verbose and we may have a bit of data to put in the URL, we will select the later. I don't want us to start inventing a new dedicated strategy to encode URLs.
| - 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+` |
There was a problem hiding this comment.
This is not relevant for this shape
|
|
||
| == 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. |
There was a problem hiding this comment.
That's completely opposite to the current or expected behavior. The URL is synchronized with the selection, if the selection changes by any mean, the URL should change and the other way around. Countless of web application are behaving like that, it's one of the core goal of the URL, it encodes a state of the application.
|
|
||
| - 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. |
There was a problem hiding this comment.
It's not at all part of this work but we need to ensure that we are not creating unusable URLs
sbegaudeau
force-pushed
the
dev/4376
branch
2 times, most recently
from
bd69167 to
546e4d6
Compare
Bug: eclipse-sirius#4376 Signed-off-by: Florent Latombe <[email protected]>
Bug: #4376
Pull request template
General purpose
What is the main goal of this pull request?
Project management
priority:andpr:labels been added to the pull request? (In case of doubt, start with the labelspriority: lowandpr: to review later)area:,difficulty:,type:)CHANGELOG.adocbeen updated to reference the relevant issues?CHANGELOG.adoc? (Including changes in the GraphQL API)CHANGELOG.adoc? For example indoc/screenshots/2022.5.0-my-new-feature.pngArchitectural decision records (ADR)
[doc]?CHANGELOG.adoc?Dependencies
CHANGELOG.adoc?CHANGELOG.adoc?Frontend
This section is not relevant if your contribution does not come with changes to the frontend.
General purpose
Typing
We need to improve the typing of our code, as such, we require every contribution to come with proper TypeScript typing for both changes contributing new files and those modifying existing files.
Please ensure that the following statements are true for each file created or modified (this may require you to improve code outside of your contribution).
useMutation<DATA_TYPE, VARIABLE_TYPE>(…)useQuery<DATA_TYPE, VARIABLE_TYPE>(…)useSubscription<DATA_TYPE, VARIABLE_TYPE>(…)useMachine<CONTEXT_TYPE, EVENTS_TYPE>(…)useState<STATE_TYPE>(…)?.(if the GraphQL API specifies that a field cannot benull, do not treat it has potentiallynullfor example)let diagram: Diagram | null = null;)Backend
This section is not relevant if your contribution does not come with changes to the backend.
General purpose
Architecture
Review
How to test this PR?
Please describe here the various use cases to test this pull request