From 605d247577c30410eb0ea6e8675c19af036e9ab5 Mon Sep 17 00:00:00 2001 From: Guillaume Fontorbe Date: Tue, 13 Feb 2024 10:19:06 +0100 Subject: [PATCH] Split documentation into two categories (#33) * Split documentation into two categories Signed-off-by: Guillaume Fontorbe * Split custom interactions documentation Signed-off-by: Guillaume Fontorbe --------- Signed-off-by: Guillaume Fontorbe --- hugo/config.toml | 5 ++- ..._protocols.md => actions-and-protocols.md} | 1 - ..._interaction.md => custom-interactions.md} | 44 +++---------------- ...y_injection.md => dependency-injection.md} | 1 - hugo/content/docs/features.md | 1 - ...{getting_started.md => getting-started.md} | 3 +- .../docs/{_index.md => introduction.md} | 3 +- hugo/content/docs/micro-layout.md | 1 - .../{model_sources.md => model-sources.md} | 1 - hugo/content/docs/overview.md | 1 - hugo/content/docs/smodel.md | 13 +++--- hugo/content/docs/svg-rendering.md | 1 - hugo/content/docs/user-interaction.md | 33 ++++++++++++++ hugo/data/menu/main.yaml | 28 ++++++++++++ hugo/layouts/partials/sprotty-header.html | 2 +- 15 files changed, 82 insertions(+), 56 deletions(-) rename hugo/content/docs/{actions_and_protocols.md => actions-and-protocols.md} (99%) rename hugo/content/docs/{user_interaction.md => custom-interactions.md} (76%) rename hugo/content/docs/{dependency_injection.md => dependency-injection.md} (99%) rename hugo/content/docs/{getting_started.md => getting-started.md} (99%) rename hugo/content/docs/{_index.md => introduction.md} (96%) rename hugo/content/docs/{model_sources.md => model-sources.md} (99%) create mode 100644 hugo/content/docs/user-interaction.md create mode 100644 hugo/data/menu/main.yaml diff --git a/hugo/config.toml b/hugo/config.toml index ce5dfa7..e62e5fa 100644 --- a/hugo/config.toml +++ b/hugo/config.toml @@ -24,4 +24,7 @@ enableRobotsTXT = true endLevel = 9 [taxonomies] - tag = "tags" \ No newline at end of file + tag = "tags" + +[params] + geekdocMenuBundle = true \ No newline at end of file diff --git a/hugo/content/docs/actions_and_protocols.md b/hugo/content/docs/actions-and-protocols.md similarity index 99% rename from hugo/content/docs/actions_and_protocols.md rename to hugo/content/docs/actions-and-protocols.md index 509b4df..832676c 100644 --- a/hugo/content/docs/actions_and_protocols.md +++ b/hugo/content/docs/actions-and-protocols.md @@ -1,6 +1,5 @@ --- title: 'Communication and Protocols' -weight: 500 --- {{< toc >}} Sprotty uses actions to communicate between `ModelSource` and `ActionDispatcher` regardless if the model source is local or remote. diff --git a/hugo/content/docs/user_interaction.md b/hugo/content/docs/custom-interactions.md similarity index 76% rename from hugo/content/docs/user_interaction.md rename to hugo/content/docs/custom-interactions.md index 5adc6a3..9bc1b3e 100644 --- a/hugo/content/docs/user_interaction.md +++ b/hugo/content/docs/custom-interactions.md @@ -1,40 +1,10 @@ --- -title: 'User Interaction' -Weight: 900 +title: 'Creating Custom Interaction' --- + {{< toc >}} -## Interacting with a Sprotty Diagram - -Sprotty offers multiple mouse and keyboard interactions by default listed in the following tables. -The `CTRL` key in the following is equal to the `CMD` key on Mac. - -| Mouse -| ----------------- | ---- | -| left-click: | toggle selection | -| CTRL-click: | add to/remove from selection | -| left-click : drag | move selection (when on selected element) | -| left-click : drag | pan viewport (when on diagram background) | -| mouse wheel: | zoom | - -| Touchpad -| --------------------- | --- | -|click | toggle selection | -|drag | move selection (when on selected element) | -|two-finger pan up/down | zoom | -|zoom | zoom | - -| Keys -| ---------- | --- | -|CTRL-SHIFT-A| select all | -|CTRL-SHIFT-C| center selection, or if nothing is selected center the entire diagram | -|CTRL-SHIFT-E| export diagram to SVG | -|CTRL-SHIFT-F| zoom selection to fill the entire canvas, or if nothing is selected zoom the entire diagram | -|CTRL-Z | undo | -|CTRL-SHIFT-Z| redo | - -## Creating Custom Interaction - -### Buttons and Button Handlers + +## Buttons and Button Handlers Buttons in Sprotty work similarly to the other model elements, but they enable you to directly hook up handlers that react to the push of a button. As in the other examples with other types of nodes, we first need to define the model and view class and define its type ID. in addition, we also need to define a button handler of type `IButtonHandler`. @@ -68,7 +38,7 @@ export class CustomButtonHandler implements IButtonHandler { } ``` -### Mouse and Keyboard Listeners +## Mouse and Keyboard Listeners Sprotty also offers the ability to attach mouse and keyboard listeners by registering `MouseListener` or `KeyListener`. This can be simply done by binding the custom listener to the respective listener type in your [DI-container](../dependency_injection) like this: @@ -91,7 +61,7 @@ export class CustomMouseListener extends MouseListener { If only specific types of nodes are supposed to be interacted with through this custom listener, it's recommended to [create a custom feature](no-link-yet). -### Projection Bars +## Projection Bars Another interactive Sprotty feature is the `ProjectedViewportView`. This view automatically adds a vertical and horizontal scrollbar to our diagram view in which our current viewport is shown, like in the following image. @@ -101,7 +71,7 @@ This view automatically adds a vertical and horizontal scrollbar to our diagram To activate this feature, instead of using `SGraphImpl` and `SGraphView` for our root element, as we did in the other examples, we use `ViewportRootElement` and `ProjectedViewportView`. The scrollbars created through `ProjectedViewportView` can be styled via the `.sprotty-viewport` and `.sprotty-projection-bar` CSS classes. -As we can see in the image, these scrollbars can contain projections of our nodes, which show their horizontal and vertical position. +As we can see in the image, these scrollbars can contain projections of our nodes, which show their horizontal and vertical position. Double-clicking on a projection will center the view on the node the projection belongs to. To add projections we add the `Projectable` type to the nodes in our model schema like this: diff --git a/hugo/content/docs/dependency_injection.md b/hugo/content/docs/dependency-injection.md similarity index 99% rename from hugo/content/docs/dependency_injection.md rename to hugo/content/docs/dependency-injection.md index ff38d62..3c8871c 100644 --- a/hugo/content/docs/dependency_injection.md +++ b/hugo/content/docs/dependency-injection.md @@ -1,6 +1,5 @@ --- title: 'Sprotty configuration and dependency injection' -Weight: 310 --- {{< toc >}} As seen in the [getting started](../getting_started) guide, Sprotty relies heavily on dependency injection (DI) through [InversifyJs](https://inversify.io/) for the configuration of its various components. This chapter will take a closer look at how to work with this. diff --git a/hugo/content/docs/features.md b/hugo/content/docs/features.md index 18ca665..7561dcf 100644 --- a/hugo/content/docs/features.md +++ b/hugo/content/docs/features.md @@ -1,6 +1,5 @@ --- title: 'Features' -weight: 301 --- {{< toc >}} diff --git a/hugo/content/docs/getting_started.md b/hugo/content/docs/getting-started.md similarity index 99% rename from hugo/content/docs/getting_started.md rename to hugo/content/docs/getting-started.md index 8b36257..b699532 100644 --- a/hugo/content/docs/getting_started.md +++ b/hugo/content/docs/getting-started.md @@ -1,6 +1,5 @@ --- title: 'Getting Started' -weight: 200 --- Our 'Getting Started' example consists of a simple application that displays a list of tasks, their status, and the relationship between them in a HTML page. @@ -52,6 +51,7 @@ Our example application is based on TypeScript. In this application we will set } } ``` + 4. Install dependencies running `npm i` 5. Initialize the TypeScript project @@ -81,6 +81,7 @@ Our example application is based on TypeScript. In this application we will set ] } ``` + 6. Create a `index.html` file at the root of your project ```html diff --git a/hugo/content/docs/_index.md b/hugo/content/docs/introduction.md similarity index 96% rename from hugo/content/docs/_index.md rename to hugo/content/docs/introduction.md index 79a41c1..bdbff6a 100644 --- a/hugo/content/docs/_index.md +++ b/hugo/content/docs/introduction.md @@ -1,6 +1,5 @@ --- -title: 'Documentation' -weight: 100 +title: 'Introduction' --- Sprotty is a next-generation, open-source diagramming framework built with web-technologies. diff --git a/hugo/content/docs/micro-layout.md b/hugo/content/docs/micro-layout.md index baba05c..16968f3 100644 --- a/hugo/content/docs/micro-layout.md +++ b/hugo/content/docs/micro-layout.md @@ -1,6 +1,5 @@ --- title: Micro-layout -weight: 400 --- {{< toc >}} The **micro-layout** refers to the layout of elements inside of a node, i.e. the layout of nested labels, buttons, etc. It is not to be confused with the **macro-layout** which refers to the layout of the entire graph, e.g. the position of nodes. diff --git a/hugo/content/docs/model_sources.md b/hugo/content/docs/model-sources.md similarity index 99% rename from hugo/content/docs/model_sources.md rename to hugo/content/docs/model-sources.md index 5fcadaa..583c15a 100644 --- a/hugo/content/docs/model_sources.md +++ b/hugo/content/docs/model-sources.md @@ -1,6 +1,5 @@ --- title: 'Model Sources' -weight: 400 --- {{< toc >}} When drawing a diagram with Sprotty we need a place to define and update the schema of the diagram to draw. Sprotty uses *model sources* to do this. diff --git a/hugo/content/docs/overview.md b/hugo/content/docs/overview.md index 9fc53d4..8651a3a 100644 --- a/hugo/content/docs/overview.md +++ b/hugo/content/docs/overview.md @@ -1,6 +1,5 @@ --- title: 'Overview' -weight: 100 --- {{< toc >}} diff --git a/hugo/content/docs/smodel.md b/hugo/content/docs/smodel.md index 989c565..d49145e 100644 --- a/hugo/content/docs/smodel.md +++ b/hugo/content/docs/smodel.md @@ -1,6 +1,5 @@ --- title: 'SModel' -weight: 300 geekdocToc: 1 --- {{< toc >}} @@ -208,11 +207,11 @@ A label represents some text to be displayed and attached to a node, compartment * `alignment: Point`: The alignment of the label. Defaults to `Point.ORIGIN`. * `opacity: number`: The opacity of the label. Defaults to `1`. * `edgePlacement: EdgePlacement` - *optional*: The placement of the label on an edge. Defaults to `EdgePlacement.NONE`. - * `rotate: boolean` - true, if the label should be rotated to touch the edge tangentially - * `side: EdgeSide` - where is the label relative to the line's direction. Possible values are 'bottom', 'top', 'left', 'right', and 'on'. - * `position: number` - between 0 (source anchor) and 1 (target anchor) - * `offset: number` - space between label and edge/connected nodes - * `moveMode: 'edge' | 'free' | 'none'` - *optional* constrains where the label can be moved when move feature is enabled for the respective Label. + * `rotate: boolean` - true, if the label should be rotated to touch the edge tangentially + * `side: EdgeSide` - where is the label relative to the line's direction. Possible values are 'bottom', 'top', 'left', 'right', and 'on'. + * `position: number` - between 0 (source anchor) and 1 (target anchor) + * `offset: number` - space between label and edge/connected nodes + * `moveMode: 'edge' | 'free' | 'none'` - *optional* constrains where the label can be moved when move feature is enabled for the respective Label. `edge` means the label can be moved along the edge, `free` means the label can be moved freely, `none` means the label cannot moved. Defaults to `edge`. @@ -313,4 +312,4 @@ To offset the anchor point of an edge *Inheritance:* -[`SChildElementImpl`](#schildelementimpl) → [`SParentElementImpl`](#sparentelementimpl) → [`SModelElementImpl`](#smodelelementimpl) \ No newline at end of file +[`SChildElementImpl`](#schildelementimpl) → [`SParentElementImpl`](#sparentelementimpl) → [`SModelElementImpl`](#smodelelementimpl) diff --git a/hugo/content/docs/svg-rendering.md b/hugo/content/docs/svg-rendering.md index a929473..463ebff 100644 --- a/hugo/content/docs/svg-rendering.md +++ b/hugo/content/docs/svg-rendering.md @@ -1,6 +1,5 @@ --- title: 'SVG Rendering' -weight: 320 --- {{< toc >}} Sprotty transforms a given `SModel` to its representation in the DOM in the form of a hierarchy of SVG elements. An `SModel` is composed of `SModelElement`s, and each `SModelElement` has a `type` property that is associated to a single corresponding `View`. The `ViewRegistry` keeps a map of the correspondence between an element type and a view. These model elements are organized in the *virtual DOM* before being rendered as actual SVG elements in the DOM. diff --git a/hugo/content/docs/user-interaction.md b/hugo/content/docs/user-interaction.md new file mode 100644 index 0000000..5545a7e --- /dev/null +++ b/hugo/content/docs/user-interaction.md @@ -0,0 +1,33 @@ +--- +title: 'User Interaction' +--- +{{< toc >}} + +## Interacting with a Sprotty Diagram + +Sprotty offers multiple mouse and keyboard interactions by default listed in the following tables. +The `CTRL` key in the following is equal to the `CMD` key on Mac. + +| Mouse +| ----------------- | ---- | +| left-click: | toggle selection | +| CTRL-click: | add to/remove from selection | +| left-click : drag | move selection (when on selected element) | +| left-click : drag | pan viewport (when on diagram background) | +| mouse wheel: | zoom | + +| Touchpad +| --------------------- | --- | +|click | toggle selection | +|drag | move selection (when on selected element) | +|two-finger pan up/down | zoom | +|zoom | zoom | + +| Keys +| ---------- | --- | +|CTRL-SHIFT-A| select all | +|CTRL-SHIFT-C| center selection, or if nothing is selected center the entire diagram | +|CTRL-SHIFT-E| export diagram to SVG | +|CTRL-SHIFT-F| zoom selection to fill the entire canvas, or if nothing is selected zoom the entire diagram | +|CTRL-Z | undo | +|CTRL-SHIFT-Z| redo | diff --git a/hugo/data/menu/main.yaml b/hugo/data/menu/main.yaml new file mode 100644 index 0000000..1fd8f07 --- /dev/null +++ b/hugo/data/menu/main.yaml @@ -0,0 +1,28 @@ +--- +main: + - name: Documentation + sub: + - name: Introduction + ref: "/docs/introduction" + - name: Overview + ref: "docs/overview" + - name: Sprotty Configuration and Dependency Injection + ref: "docs/dependency-injection" + - name: SVG Rendering + ref: "docs/svg-rendering" + - name: Micro-layout + ref: "docs/micro-layout" + - name: Model Sources + ref: "docs/model-sources" + - name: Communication and Protocols + ref: "docs/actions-and-protocols" + - name: Creating Custom Interactions + ref: "docs/custom-interactions" + - name: Reference + sub: + - name: SModel + ref: "docs/smodel" + - name: Features + ref: "docs/features" + - name: User Interaction + ref: "docs/user-interaction" diff --git a/hugo/layouts/partials/sprotty-header.html b/hugo/layouts/partials/sprotty-header.html index f10616c..5095345 100644 --- a/hugo/layouts/partials/sprotty-header.html +++ b/hugo/layouts/partials/sprotty-header.html @@ -3,7 +3,7 @@