Skip to content
This repository was archived by the owner on Oct 21, 2025. It is now read-only.

Add optional node annotations and editor modes#42

Merged
hlxid merged 15 commits intomainfrom
feat/node-annotations
Feb 21, 2024
Merged

Add optional node annotations and editor modes#42
hlxid merged 15 commits intomainfrom
feat/node-annotations

Conversation

@hlxid
Copy link
Collaborator

@hlxid hlxid commented Feb 21, 2024

This PR adds two things interacting with each other:

  • Optional Node Annotations
  • Editor Modes

Node Annotations

Adds optional annotation to DFD nodes.
These include a mandatory message, optional color and optional (FontAwesome Free) icon.
For nodes that have an annotation a popup will open when hovering over them.
This popup shows the annotated message. This could be an analysis warning/error or pretty much anything.
When the icon is set the FontAwesome icon with the provided id will be prepended to the annotation message.
When the color of the annotation is set, the node will have a border in that color and a background with a dimmed version of that color.

The only way to add an annotation to a node is to set the annotation object inside the JSON object for the node.
These can be included when generating the diagram from other sources. There is no way to add annotations using the editor itself, that is (currently) not an intended use case.
Here's an example annotation:

{
    // rest of the node
    "annotation": {
        "message": "This node has a invalid output port/pin with an erroneous behavior definition",
        "icon": "bug",
        "color": "#ff0000"
    }
}
  • message must always be set when annotation is set to an object.
  • icon can be the id of any FontAwesome Free icon. Note that always the solid version of the icon is used, all other versions are only available with FontAwesome Pro at the point of writing, so you couldn't use the other versions anyway.
  • color can be undefined/not included or any color. Theoretically the current implementation would allow any valid CSS color definition, like red or rgba(...) but for stability it is recommended to only use hex definitions of RGB colors (like shown above). Only those are guaranteed to be supported in the future. When no color is provided the node will have the default color like not annotated nodes, meaning white/black depending on white/dark mode.

Editor Modes

Another thing this PR adds are three editor modes:

  • edit: the functionality like before this PR. You can view the diagram, change labels, move elements, create new nodes/ports/edges, etc.
  • annotated: This is the intended mode for viewing node annotations that are introduced above. With this mode the model is in a readonly state. However there is a button in the UI that allows to change the diagram to edit mode. This will delete all annotations and make the model editable. Intended for viewing errors/validation messages from the DFD analysis. After viewing the annotations the user can delete them and perform the necessary fixes in the diagram.
  • readonly: Similar to annotated. The model is in a readonly state, however there is no UI button to change the editor to the edit mode. Intended for generated diagrams from other sources.

When the model is in a readonly state the user cannot create new elements, delete elements, change the DFD or node labels, etc. However the user can still look around the diagram, view DFD output port behaviors, view node annotations by hovering on the respective nodes, etc.

The editor mode is saved inside the model JSON as an extra top level field.
E.g.

{
    "model": {/* ... */},
    "labelTypes": [/* ... */],
    "editorMode": "annotated"
}

When there is no editor mode set in the JSON representation of the model, the edit mode is used for backwards compability.

@hlxid
Copy link
Collaborator Author

hlxid commented Feb 21, 2024

Here's also an version of the current default start diagram with two added annotations.
This can be used for testing the feature.
annotatedTestDiagram.json

@sebinside
Copy link
Member

Example of the result:
image

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants