Drawio

Nasdankia provides two Maven modules for working with Drawio diagrams - API and Model. The modules require Java 17 or above.

• API
• Page and element links
• Generating documentation sites
• Executable diagrams
  • Invocable URIs
  • Java
  • Semantic mapping
• Ecore Model

API

Drawio module provides Java API for reading and manipulating Drawio diagrams. It is built on top of Graph.

The module provides the following interfaces representing elements of a diagram file:

• Document - the root object of the API representing a file/resource which contains one or more pages.
• Page - a page containing a diagram (Model).
• Model - a diagram model containing the diagram root.
• Root - the root of the model containing layers.
• Layer - a diagram may have one or more layers. Layers contain Nodes and Connections.
• Node - a node can be connected to other nodes with connections. A node may contain other nodes and connections.
• Connection - a connection between two nodes.

The below diagram shows relationships between the above interfaces including their super-interfaces:

Util provides utility methods such as layout() and methods to navigate and query documents and their elements.

• Sources
• JavaDoc

Page and element links

Nasdanika Drawio API extends the concept of linking to pages to cross-document linking to pages and page elements by name or ID. Link targets (pages or elements) are available via getLinkTarget() method.

Drawio page links have the following format: data:page/id,<page id> with page/id being the “media type” and <page id> being the “data” of a Data URL.

Nasdanika Drawio API extends it to additional media types:

• page/name
• element/id
• element/name

The data (selector) format has the following format:

• Page: [<diagram resource>#]<page selector>
  • Diagram resource is a URI resolved relative to the current document URI. If not present then the link target page is in the same document.
  • Page selector is either page ID or URL encoded page name depending on the media type - id or name.
• Element: [<diagram resource>#][<page selector>/]<element selector>]
  • Diagram resource is a URI resolved relative to the current document URI. If not present then the link target element is in the same document.
  • Page selector is either of:
    • id,<page id>
    • name,<URL encoded page name>
  • Element selector is either page ID or URL encoded element label text (stripped of HTML formatting) depending on the media type - id or name.

For elements URL’s page selector is required if diagram resource URI is present.
Examples:

• Page links:
  • data:page/name,compressed.drawio#Page-1 - Link to compressed first page
  • data:page/name,compressed.drawio#Page+2 - Link to compressed second page
• Element links:
  • data:element/id,7KSC1_O8d7ACaxm1iSCq-1 - Link by ID to an element on the same page
  • data:element/name,name,Page+2/Linked - Link by name to Linked on Page 2 referenced by name
  • data:element/name,compressed.drawio#name,Page+2/Linked - Link to Linked on compressed second page

This approach allows to create a multi-resource graph of diagrams. Nasdanika Drawio API also supports loading of documents from arbitrary URI’s using a URI resolver. For example, maven://<gav>/<resource path> to load from Maven resources or gitlab://<project>/<path> to load resources from GitLab without cloning a repository, provided there is a handler (Function<URI,InputStream>) supporting the aforementioned URI’s.

Generating documentation sites

With Nasdanika CLI drawio > html-app > site command pipeline can be used to generate documentation web sites from Drawio diagrams:

• Demo
• Video explaining how the above demo was created
• Template repository
• Internet Banking System - another demo: a sample C4 Model
• Visual Communication Continuum - a Medium story which provides an overview of the approach and compares it with semantic mapping

Executable diagrams

With Nasdanika Drawio API and other products you can make your diagrams executable as explained in the following sections.

Invocable URIs

You may set diagram element properties to URIs of processors. This approach is explained in General Purpose Executable Graphs and Diagrams Medium story. A demo repository is here - https://github.com/Nasdanika-Demos/executable-diagram-dynamic-proxy. You can use this site/ repository as a starting point for your diagramming ecosystem:

• Site
• Code

Java

You can create graph element processors for diagram elements in Java.

Executable (computational) graphs & diagrams story provides a high level overview of executable graphs and diagrams. Graph documentation features more technical details and code samples. Compute Graph Demo provides examples of this and semantic mapping (below) approaches using the compute graph from the “Executable (computational) graphs & diagrams” story.

Semantic mapping

Semantic mapping is mapping of diagram elements to a semantic model and then making the model executable, possibly using graph processors. Visual Communication Continuum story provides an overview of semantic mapping and when to use it comparing to “direct generation”. Beyond Diagrams book explains the mapping approach in more detail.

Ecore Model

Drawio Model module provides an EMF Ecore model for diagrams. A model instance can be obtained from the API document by calling Document.toModelDocument() method.

The model makes it more convenient to work with the diagram elements by:

• Making links from diagram elements to pages and other diagram elements bi-directional.
• Introducing Tag class as opposed to a string in the API. Tag is contained by Page and has bi-directional reference with tagged elements.

• Sources

• JavaDoc