Merge pull request #99 from eclipse-glsp/2.0

Update documentation for GLSP 2.0

.vscode/settings.json

@@ -17,6 +17,6 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
   "[markdown]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
   }
 }

content/documentation/actionhandler/content.md

@@ -286,33 +286,6 @@ protected override configureActionHandlers(binding: InstanceMultiBinding<ActionH
 </details>
 </br>
 
-In addition, each response action of the handler that should be handled by the _GLSP client_ has to be configured as dedicated client action to indicate that it needs to be dispatched to the client:
-
-<details open><summary>Java GLSP Server</summary>
-
-```java
-protected void configureClientActions(final MultiBinding<Action> binding) {
-    super.configureClientAction(binding);
-    binding.add(MyCustomRequestAction.class);
-}
-```
-
-</details>
-
-<details><summary>Node GLSP Server</summary>
-
-```ts
-protected configureClientActions(
-    binding: InstanceMultiBinding<string>
-): void {
-    super.configureClientActions(binding);
-    binding.add(MyCustomRequestAction.KIND);
-}
-```
-
-</details>
-</br>
-
 #### Request-Response Handling
 
 Action handlers can treat request-response actions in the same way as plain actions.
@@ -349,6 +322,3 @@ const diagramModule = new ContainerModule((bind, _unbind, isBound, rebind) => {
 
 The `configureActionHandler()` function takes the inversify binding context, the action kind that should be handled, and the action handler class, as input.
 It registers the action handler for the given action kind, so that it can be retrieved by the action dispatcher.
-
-Note that we don’t have to explicitly declare which actions are handled by the GLSP Server.
-The GLSP server sends this information during the initialization process and the GLSP client automatically sets up the necessary action (handler) registrations.

content/documentation/clientLayouting/content.md

@@ -103,7 +103,7 @@ Therefore please use the dedicated string values in the meantime, e.g. `"hAlign"
 
 In general, layouters can be applied to elements that are compartments, in order to layout the containers based on the sizes of their children.
 
-There are four built-in layout types that can be used: `hbox`, `vbox`, `freeform` and `stack`.
+There are three built-in layout types that can be used: `hbox`, `vbox` and `freeform`.
 
 ##### `hbox` Layout
 
@@ -167,7 +167,7 @@ GCompartment.builder()
 
 </br>
 
-On the client side, we need to configure (besides the default elements `SCompartment` and `SLabel`) a custom `Icon` element and a `IconView` like this: `configureModelElement(context, 'icon', Icon, IconView)`.
+On the client side, we need to configure (besides the default elements `GCompartment` and `GLabel`) a custom `Icon` element and a `IconView` like this: `configureModelElement(context, 'icon', Icon, IconView)`.
 The [`Icon` element definition](https://github.com/eclipse-glsp/glsp-client/blob/master/examples/workflow-glsp/src/model.ts) and the [`IconView` definition](https://github.com/eclipse-glsp/glsp-client/blob/master/examples/workflow-glsp/src/workflow-views.tsx) are taken from the workflow example.
 
 The resulting element with the obvious horizontal gap between the child elements is shown in the following image:
@@ -317,7 +317,7 @@ GCompartment.builder()
 
 </br>
 
-On the client side, configure the `"comp:structure"` compartment as `configureModelElement(context, 'struct', SCompartment, StructureCompartmentView)`.
+On the client side, configure the `"comp:structure"` compartment as `configureModelElement(context, 'struct', GCompartment, StructureCompartmentView)`.
 
 The resulting compartment element positions its child at the desired position.
 The compartment defines its preferred size, which is used if the children do not enlarge the container. If the preferred size is omitted, the container's size depends on its children.
@@ -331,102 +331,6 @@ The compartment defines its preferred size, which is used if the children do not
 
 </br></br>
 
-#### Default Sprotty Layouters
-
-It is also possible to use default sprotty layouts, like for example the `stack` Layout as shown below in the example.
-Here it is necessary to use the sprotty specific Layouter which is available via sprotty's [`boundsModule`](https://github.com/eclipse/sprotty/blob/master/packages/sprotty/src/features/bounds/di.config.ts), which is also part of the GLSP client container's [default modules](https://github.com/eclipse-glsp/glsp-client/blob/master/packages/client/src/base/container-modules.ts).
-However, we recommend using GLSP layouts.
-
-##### `stack` Layout</br>
-
-The [`StackLayouter`](https://github.com/eclipse/sprotty/blob/master/packages/sprotty/src/features/bounds/stack-layout.ts) positions the children by stacking them on top of each other considering the given alignment.
-
-This layouter provides additional layout options via `StackLayoutOptions`:
-
-- `vAlign`: VAlignment = 'top' | 'center' | 'bottom'</br>
-  Defines the vertical alignment of the element to be positioned.
-- `hAlign`: HAlignment = 'left' | 'center' | 'right'</br>
-  Defines the horizontal alignment of the element to be positioned.
-
-The children of the container are positioned according to their order and the defined alignment. Based on that, the maximum height and width are computed and are used as bounds for the container.
-
-<details><summary>`stack` Layout Example</summary>
-
-This example creates a compartment of the custom type `"comp"` using the `stack` layout.
-It adds two child nodes - a circle a node and a text label - that are stacked on top of each other.
-
-<details open><summary> Java GLSP Server</summary>
-
-```java
-  Map<String, Object> layoutOptions = new HashMap<>();
-  layoutOptions.put(GLayoutOptions.KEY_H_ALIGN, GConstants.HAlign.CENTER);
-  layoutOptions.put(GLayoutOptions.KEY_RESIZE_CONTAINER, false);
-  new GCompartmentBuilder()
-    .type(DefaultTypes.COMPARTMENT)
-    .layout(GConstants.Layout.STACK)
-    .layoutOptions(layoutOptions)
-    .size(GraphUtil.dimension(35, 35))
-    .add(
-      new GNodeBuilder("circle")
-        .size(GraphUtil.dimension(35, 35))
-        .build()
-    )
-    .add(
-      new GLabelBuilder()
-        .text("A")
-        .addCssClass("circle-letter")
-        .build()
-    )
-    .build();
-```
-
-</details>
-
-<details ><summary> Node GLSP Server</summary>
-
-```ts
-const layoutOptions = {
-  ["hAlign"]: "center",
-  ["resizeContainer"]: false,
-};
-GCompartment.builder()
-  .type("comp")
-  .layout("struct")
-  .addLayoutOptions(layoutOptions)
-  .add(GNode.builder().type("circle").size(35, 35).build())
-  .add(GLabel.builder().text("A").addCssClass("circle-letter").build())
-  .build();
-```
-
-</details>
-
-</br>
-
-On the client side, please make sure that sprotty's [`boundsModule`](https://github.com/eclipse/sprotty/blob/master/packages/sprotty/src/features/bounds/di.config.ts) is registered.
-
-The `"circle"` node element has to be configured as `configureModelElement(context, 'circle', CircularNode, CircularNodeView)`.
-
-To style the letter label, we add this simple CSS rule as well:
-
-```css
-.circle-letter {
-  fill: lightsteelblue;
-}
-```
-
-The resulting compartment positions its children on top of each other and centers the label horizontally.
-
-<p align="center">
-    <img src="./struct-layout-example.png" alt="freeform-layout-example">
-</p>
-<p  align="center">
-    <em>Container that stacks its children and positions the label to the left (1), in the center (2) and to the right (3)</em>
-</p>
-
-</details>
-
-</br></br>
-
 #### Custom Layouter
 
 Additional custom layouters can be contributed by creating a layouter class that extends the `AbstractLayouter` and optionally provide custom options that extend the `AbstractLayoutOptions`.
@@ -446,7 +350,7 @@ export class MyCustomLayouter extends VBoxLayouterExt {
   static override KIND = "myCustomLayout";
 
   protected override getChildrenSize(
-    container: SParentElement & LayoutContainer,
+    container: GParentElement & LayoutContainer,
     containerOptions: MyCustomLayoutOptions,
     layouter: StatefulLayouter
   ): Dimension {

content/documentation/gmodel/content.md

@@ -34,15 +34,15 @@ The graphical model is typically composed of the following elements.
     - **GCompartment**: A generic container element used for element grouping
   - **GEdge**: A diagram edge that connects a source element and a target element (typically nodes or ports).
 
-#### SModel: Graphical model on the client
+#### Graphical model on the client
 
 The default GLSP client uses [Sprotty](https://github.com/eclipse/sprotty), an SVG-based diagramming framework, to render diagrams.
 Sprotty uses a model to represent a diagram too -- the so-called `SModel`.
 The graphical model of GLSP is based on the SModel and, thus, can be seen as a compatible extension of the Sprotty model.
-
-As a naming convention, GLSP uses the S-prefix for model elements on the client to conform to the naming of the Sprotty model.
-Thus, a node of the graphical model on the GLSP client is called `SNode`, whereas it is called `GNode` on the server, the same is true for `SEdge` / `GEdge`, etc.
-Semantically, those elements, however, are equivalent and are exchanged transparently between the server and the client via JSON-RPC.
+To ensure a consistent development experience GLSP aliases all reused `SModel` types to the `GModel` namespace.
+For instance sprotty's `SModelElementImpl` is equivalent to GLSP's `GModelElement`.
+There should almost never be a reason to directly use the sprotty types. If possible always try to use the `GModel` API when developing
+on the client.
 
 #### GModel: Graphical model on the server
 
@@ -180,10 +180,10 @@ As an example, let’s have a look at the custom WeightedEdge element introduced
 #### GLSP Client
 
 A WeightedEdge is a special edge that has an optional “probability” property.
-We can define such an element by simply subclassing the `SEdge` class:
+We can define such an element by simply subclassing the `GEdge` class:
 
 ```ts
-export class WeightedEdge extends SEdge {
+export class WeightedEdge extends GEdge {
   probability?: string;
 }
 ```

content/documentation/modelOperations/content.md

@@ -10,6 +10,8 @@ title = "Model Operations"
 
 ### Operations are just special actions
 
+> _**Remark:**_ This documentation is outdated and not updated for GLSP 2.0 yet!
+
 In the previous section, we discussed [actions and action handlers]({{< relref  "actionhandler" >}}) as the general way of how a diagram client and a diagram server communicate with each other and how they can invoke behavior or query data from each other.
 If such a behavior of an action now is intended to change the [underlying source model]({{< relref "sourceModel" >}}) on the server, there is a dedicated type of action for that: _a model operation_ or operation for short.