Skip to content

Add diagrams.net support to Gitlab Wikis (Markdown).

Mohamed Mohamedin requested to merge mohamedin/gitlab:drawio into master

What does this MR do?

It implements support for creating and editing diagrams using the diagrams.net editor in Wikis.

How to test in your local environment?

  1. Edit or create a Wiki page.
  2. Switch to Markdown mode if you are using the Content Editor to edit the Wiki page’s content.

To create a diagram:

  1. Click the Insert or edit diagram toolbar button in the Markdown editor.
  2. Use the diagrams.net editor to build the diagram.
  3. Click Save & exit.
  4. The Markdown field will insert a Markdown image declaration pointing to the diagram created.

To edit a diagram:

  1. Place the Markdown editor’s text field cursor in a Markdown image declaration that contains the diagram.
  2. Click the Insert or edit diagram toolbar button in the Markdown editor.
  3. Use the diagrams.net editor to build the diagram.
  4. Click Save & exit.
  5. The Markdown field will replace the previous Markdown image declaration pointing to the diagram created.

Screenshots

Markdown field Draw.io Editor Entering diagram name Diagram saved successfully Failed to load diagrams.net editor Failed to load existing diagram
2023-02-06_20.26.58 Screenshot_2023-01-24_at_6.03.56_PM Screenshot_2023-01-24_at_6.04.15_PM Screenshot_2023-01-24_at_6.10.12_PM Screenshot_2023-01-24_at_6.11.25_PM

Implementation details

The diagrams are saved as SVG files that use the drawio.svg extension and uploaded using GitLab’s user uploads API.

The diagrams.net editor is embedded in the GitLab application using an iframe. The iframe and the GitLab application communicate using the postMessage API. There are two main communication workflows between the draw.io iframe and the GitLab application: loading a diagram and saving a diagram.

sequenceDiagram
    participant A as drawio_editor.js (container)
    participant B as diagrams.net (iframe)
    A->>+B: postMessage('configure', { darkMode })
    B-->>-A: postMessage('init')

Loading a diagram

  • The GitLab application will send a configure message to the draw.io iframe that indicates whether GitLab is in Dark mode and sets GitLab settings preset.
  • The diagrams.net iframe will reply with an init message to the GitLab application.
  • If there is a draw.io diagram selected in the Markdown field, the EditorFacade will download the diagram and the GitLab application will load it into the draw.io editor.
  • Otherwise, the GitLab application sends a load message with an empty payload.

Saving a diagram

  1. The diagrams.net iframe will send an export message to the GitLab application when the user clicks "Save & Exit".
  2. If the unsaved diagram doesn’t have a name. 3. The gitlab application will send a prompt message to display a filename dialog in the diagrams.net editor. 4. The diagrams.net editor will send a prompt message back to the GitLab application with the filename entered by the user.
  3. When the filename is set, the GitLab application will upload the diagram as an SVG file.
  4. It will insert a Markdown image declaration pointing to the diagram SVG file.

Markdown field editor facade

The markdown_field_editor_facade.js module is a bridge between the diagrams.net editor and the markdown_field component. The goal of this module is keeping the diagrams.net editor agnostic from text editors. It will allow us to implement support for this editor in the Content Editor as well.

Next steps

Related to #322174 (closed)

Edited by Enrique Alcántara

Merge request reports