A skim back through this blog will turn up several posts over the years on the topic of “writing diagrams”, using text based scripts along with diagram generating applications to create diagrams from textual descriptions.
There are a several reasons I think such things useful, particularly in online, distance education context in an institution with a factory production model:
- diagram generation can be automated, with standardised style / rendering of the diagram separated from it’s logical description;
- maintaining diagrams is simplified: change the underlying text to change the logical content of the diagram, or change the rendering pipeline to change the output design or format;
- search: if you can search the text used to generate a diagram as well text that appears within a diagram, it supports discovery;
- accessibility: if we generate diagrams from text, there is a good chance we could also generate equivalent textual descriptions of diagrams from the same text.
Sometimes, though, it can be handy to be able to actually draw a diagram by actually drawing it, rather than generating it from a textual source.
Recently, I came across draw.io, via the jupyterlab-drawio extension. draw.io is a web-based [code] or electron app wrapped [code] SVG editor. draw.io is actually a front end application built on top of the mxGraph JavaScript diagramming library and based on the example GraphEditor.
When you create a new diagram, you are prompted for a save location:
Local (device) storage is the default, but it looks like you can also link Google Drive or OneDrive online storage, though I haven’t tried this (yet!):
If you have a previously saved diagram, you can select it from a file browser. If you opt to create a new diagram, you can create a blank diagram with a default set of drawing tools, a particular diagram type or a diagram imported from a template URL:
If you go for the template URL option, you are prompted for the URL (I don’t know if there’s a catalogue / awesome list of template URLs anywhere?):
If you select one of the canned diagram type options, you are provided with a preview of the sorts of diagram you can create within that view:
If you click to select one of the example diagrams then click Create, the diagram editor opens with the example diagram and a set of custom diagram element options in the scratchpad sidebar:
If you don’t select a preview diagram, or you select the Blank diagram, you just get a default tool set.
Usefully for the course I’m looking at, one of the scratchpad collections provides diagram components that can be used to draw Crows Foot entity relation diagrams, as described here: Entity Relationship Diagrams with draw.io (see also: Entity Relationship Diagram (ERD)).
Clicking on an item in the toolbar previews the component and adds it to the canvas; you can also click and drag items from the sidebar and then drop them on the canvas.
(Partial) ERD diagrams can also be generated by importing database table definitions using the SQL import plugin.
Writing Diagrams
One of the nice features of draw.io is that you can also generate certain diagrams from data files. In the Arrange menu, the Insert option provides several options for importing different sorts of data or textual elements from which diagrams can be automatically generated.
Plugins extend the range of import options, as for example in the case of the sql-plugin. (The SQL plugin seems to add tables based on CREATE TABLE elements in the SQL; whilst it correctly identifies and highlights primary keys, it doesn’t identify relationships between them, so you have to add the crow’s foot lines yourself…)
See the full list of official plugins.
Data can be imported from CSV files, as described here: Automatically create draw.io diagrams from CSV files Not all columns need to be displayed; some columns may even be used to store metadata or styling information using reserved columns ( image, fill and stroke ). The first column in each row represents a node and may be styled according to details given in the styling columns.
Other columns contain values that can be included in the node or that specify which other nodes that node is connected to. Rules are used to define the styling and labelling of each edge, as well as identifying columns used to identify edge connections between nodes.
Not all columns need to be referenced / used in the diagram that is generated.
I haven’t fully explored all the possible CSV import settings yet; I’m also thinking it’d be nice if there were some Python tooling to help simplify the creation of the CSV import definition file.
(By the by, there is also a handy online CSV viewer webform available.)
As well as CSV import, UML diagrams can be generated using PlantUML, a tool for creating a wide variety of diagram types from imported UML and other diagram specifications: Use PlantUML in draw.io. (That said, when I tried with the online *draw.io editor, the PlantUML import didn’t work. It looks like it uses Graphviz underneath, so it may be something to do with that? I need to try on a local install really, or ideally in a container with JupyterLab using the jupyterlab-drawio extension.)*
Taken together, I wonder if these importers could be used with other Python tools for generating diagrams from code? e.g. could something like this approach to electrical circuit diagram generation with lcapy be used to generate diagrams that draw.io can render??
Another handy looking too comes in the form of drawio-batch, a “command line converter for draw.io diagrams” based on puppeteer (“a Node library which provides a high-level API to control Chrome”, operating it by default in headless mode) that wraps the online draw.io conversion code into an offline tool. (I’ve not had a chance to try this yet; from the tests, it looks like you call it with a draw.io XML diagram file and and output file and it gives you an output diagram back in a format corresponding to the filetype you specified by the output file suffix (pdf and svg in the tests)? Puppeteer it also new to me; a bit like Selenium, methinks, and a Javascript follower on from the now deprecated phantom.js?)
Of the plugins, replay looks interesting: it lets you render an animated version of a diagram, for example as you build up a complex flow diagram a piece at a time. There is also an anim plugin for what looks like creating more general animations.
All in all, it looks to be really handy, and something I could ship in out VM. The jupyterlab-drawio extension shows it works in JupyterLab, and I think it should also work with nbserverproxy?
By the by, the Google Drive / OneDrive integration was interesting (if it works; I haven’t had a chance to try it yet)… In particular, it makes me wonder: could the code that did that be reused to provide a similar storage workflow in JupyterHub?
PS in passing, there may be other useful tools in here — 10 JavaScript libraries to draw your own diagrams. (It’s been some time since I last did a round-up…)
PPS DDL from draw.io ER script: https://github.com/mikitex70/schema2script
OUseful.Info, the blog... 