Nasdanika

Drawio

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

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.

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, ID, or SpEL expression. 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
  • spel - Uses a SpEL expression to evaluate the link target in the context of the current element. Format: data:spel,<expression>

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.

Magic properties

The API implements placeholder interpolation %<property name>% in the same way as Draw.io does if the “Placeholders” checkbox is checked. It also adds two “magic” properties to help with using model element values in structured properties. For example, you may have a property with YAML configuration with some values computed from the element properties.

$style

Evaluates to a value of the style key provided after the colon.

Example: $style:fillColor

$spel

Evaluates a Spring Expression Langauge (SpEL) expression.

Example: $spel:style["fillColor"]

Generating documentation sites

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

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:

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.

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