Nasdanika
Core
HTML
Architecture
PlantUML Diagram Generator
Demos

Drawio

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

To use the module add the below dependency to your pom.xml:

<dependency>
	<groupId>org.nasdanika.core</groupId>
	<artifactId>drawio</artifactId>
	<version>...</version>
</dependency>

See https://mvnrepository.com/artifact/org.nasdanika.core/drawio for the latest version.

The module requires Java 11 or above.

Overview

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

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

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

Examples

  • Actions - Demo of generation of a web site from a drawio diagram
  • Flow - Demo of generation of a web site from a flow drawio diagram
  • Mind map - Demo of generation of a web site from a (mind) map drawio diagram

Creating a new document

To create a new document use Document.create():

Document document = Document.create(false, null);
Page page = document.createPage();
page.setName("My first new page");
		
Model model = page.getModel();
Root root = model.getRoot();
List<Layer> layers = root.getLayers();
		
// Add layer
Layer newLayer = root.createLayer();
newLayer.setLabel("My new layer");
				
// Add nodes
Node source = newLayer.createNode();
source.setLabel("My source node");
Rectangle sourceGeometry = source.getGeometry();
sourceGeometry.setX(200);
sourceGeometry.setX(100);
sourceGeometry.setWidth(70);
sourceGeometry.setHeight(30);
source.getTags().add("aws");
				
Node target = newLayer.createNode();
target.setLabel("My target node");
target.getGeometry().setBounds(300, 150, 100, 30);
Set<String> targetTags = target.getTags();
targetTags.add("aws");
targetTags.add("azure");
		
// Add connection 
Connection connection = newLayer.createConnection(source, target);
connection.setLabel("My connection");
Map<String, String> connectionStyle = connection.getStyle();
connectionStyle.put("edgeStyle", "orthogonalEdgeStyle");
connectionStyle.put("rounded", "1");
connectionStyle.put("orthogonalLoop", "1");
connectionStyle.put("jettySize", "auto");
connectionStyle.put("html", "1");
				
Files.writeString(new File("new-uncompressed.drawio").toPath(), document.save(null));

Loading

To load use one of load() methods. The below snippet loads from a class loader resource.

Document document = Document.load(getClass().getResource("compressed.drawio"));

It is also possible to load a document from PNG metadata - this can be used with PNG files generated by Drawio editors with “Include copy of my diagram” checked.

List<Document> documents = Document.loadFromPngMetadata(getClass().getResource("illustration.png"));

Saving

Document content can be retrieved as a String using save() method:

Files.writeString(new File("compressed.drawio").toPath(), document.save(null));

To embed a diagram into HTML use toHtml() method:

Files.writeString(new File("compressed.html").toPath(), document.toHtml(null, "https://cdn.jsdelivr.net/gh/Nasdanika/drawio@dev/src/main/webapp/js/viewer-static.min.js"));

Layout

The API provide a simple layout algorithm which arranges nodes so that they don’t overlap. It can be used with generated diagrams to make them easier to layout manually after generation.

org.nasdanika.drawio.Util.layout(root, 20);

Page linking

The API extends the page linking concept of Drawio to link an element in one document to a page in another document. This allows to create a tree/network of linked diagrams. For example, a complex system or process may be modeled in multiple diagrams maintained by multiple teams.

To link a page in another document (file):

  • To link to the first page in the document set link to data:page,<URL>, where <URL> is resolved relative to the URL of the current document. Example: data:page,compressed.drawio.
  • To link to a specific page set link to data:page/name,<URL>#<URL encoded page name>. Example: data:page/name,compressed.drawio#Page+2

Traversing

To traverse document elements you can use either accept(<visitor>) methods or stream() method.

EMF

DrawioResource

org.nasdanika.drawio.emf.DrawioResource is a base class for mapping of diagram elements to EMF Ecore model elements. With DrawioResource Drawio files are treated as model resources which can be loaded into a resource set and as such reference model elements in other resources and be referenced from other resources. org.nasdanika.html.model.app.drawio.ResourceFactory is a concrete implementation for mapping diagram elements to application model actions.

DrawioEObjectFactory

org.nasdanika.drawio.emf.DrawioEObjectFactory is a specialization of org.nasdanika.graph.processor.emf.PropertySourceEObjectFactory for Drawio diagrams. It loads semantic information from properties of diagram elements as explained below. DrawioEObjectFactory is abstract. It does not dictate semantic specification format - subclasses shall implement T load(String spec, URI specBase, ProcessorConfig<T> config, ProgressMonitor progressMonitor) method.

Conifguration properties

link-page

By default semantic elements from linked pages are wired in the same way as element children. To disable wiring of linked page elements set this property to false.

Sorting

org.nasdanika.drawio.comparators package contains comparators for sorting diagram elements based on their label, properties, and geometry.

Executable diagrams

Graph documentation explains how to implement graph processors which can be used to make diagrams executable.

Applications

This section lists some possible applications of Drawio Java API and semantic mappings:

  • High Level Design -> Low Level Design -> Implementation. Define High Level Design in diagrams. Then generate a web site with documentation for Low Level Design. Then use semantic mapping or executable diagrams approach to either generate code from diagrams or execute diagrams directly.
  • Documentation/books/video courses - create a mind map, generate a site from it, add documentation to diagram elements.
  • Reporting - create a diagram of your system/business/effort, generate a documentation site. Enrich diagrams with status - implementation status for systems being built pulled from issue tracker(s), system health status pulled from monitoring systems.