Skip to main content

Diagrams

Overviewโ€‹

Diagrams-as-code.

Allows using syntax for multiple visualization libraries inside HTML to produce diagrams. The rendered diagrams are added to the result page as either:

  • SVG elements (which you can style with CSS or manipulate with JavaScript)
  • HTML images (which you can right-click and save or open in a new window)

Diagrams from multiple libraries can be used in the same page. Only the libraries used will be loaded in the LiveCodes playground. The result page will have no libraries (only the output SVG or images).

Open starter template in LiveCodes

Usageโ€‹

This code: (open in LiveCodes)

<div data-src="my-diagram"></div>

<script type="application/diagram-mermaid" data-output="my-diagram">
  graph TD
    A-->B
    A-->C
    B-->D
    C-->D
</script>

produces this output:

flow-chart

Steps

1. Add a diagram target:โ€‹

The target element should have a data-src attribute.

It can be an HTML element (the SVG of the diagram will be embedded as a child element)

<div data-src="my-diagram"></div>

becomes

<div data-src="my-diagram"><svg ...>...</svg></div>

or an HTML image element (the diagram will be added to its src attribute as a data URL)

<img data-src="my-diagram" />

becomes

<img data-src="my-diagram" src="data:image/svg+xml;base64,..." />

There can be more that one target element for the same diagram if they have the same data-src attribute.

<div data-src="my-diagram"></div>
<img data-src="my-diagram" />

2. Add a script element with the diagram syntax:โ€‹

It should have:

  • an attribute type="application/diagram-{diagram type}" that specifies the diagram type (e.g. type="application/diagram-mermaid").
  • a data-output attribute that matches the data-src attribute of the target element.
  • the syntax of the diagram is the content of the script element or the content of a file linked by the src attribute.
<script type="application/diagram-mermaid" data-output="my-diagram">
  graph TD
    A-->B
    A-->C
    B-->D
    C-->D
</script>

<script
  type="application/diagram-mermaid"
  data-output="second-diagram"
  src="/url/to/diagram/syntax"
></script>

Supported Librariesโ€‹

Cytoscapeโ€‹

The diagram syntax is JSON representing Cytoscape options.

Please note that reference to JavaScript objects cannot be used.
e.g. do not use {container: document.getElementById('cy')}.

Example: (open in LiveCodes)

<div data-src="cytoscape.svg"></div>
<script type="application/diagram-cytoscape" data-output="cytoscape.svg">
  {
    "elements": [
      {
        "data": { "id": "a" }},
      {
        "data": { "id": "b" }},
      {
        "data": { "id": "ab", "source": "a", "target": "b" }}],

    "style": [
      {
        "selector": "node",
        "style": {
          "background-color": "#666",
          "label": "data(id)"}
      },

      {
        "selector": "edge",
        "style": {
          "width": 3,
          "line-color": "#ccc",
          "target-arrow-color": "#ccc",
          "target-arrow-shape": "triangle",
          "curve-style": "bezier"
        }
      }
    ],

    "layout": {
      "name": "grid",
      "rows": 1
    }

  }
</script>

ELKโ€‹

Diagram layout is produced using elkjs and rendered using elkjs-svg.

The syntax used is ELK JSON format.
ELK text format is not supported! (You may use this tool to convert formats)

Example: (open in LiveCodes)

<div data-src="elk.svg"></div>
<script type="application/diagram-elk" data-output="elk.svg">
  {
    "id": "root",
    "layoutOptions": {
      "elk.algorithm": "layered"
    },
    "children": [
      {"id": "n1", "width": 70, "height": 70},
      {"id": "n2", "width": 70, "height": 70},
      {"id": "n3", "width": 70, "height": 70},
      {"id": "n4", "width": 70, "height": 70},
      {"id": "n5", "width": 70, "height": 70},
      {"id": "n6", "width": 70, "height": 70}
    ],
    "edges": [
      {"id": "e1", "sources": ["n1"], "targets": ["n2"]},
      {"id": "e2", "sources": ["n1"], "targets": ["n3"]},
      {"id": "e3", "sources": ["n2"], "targets": ["n4"]},
      {"id": "e4", "sources": ["n3"], "targets": ["n5"]},
      {"id": "e5", "sources": ["n5"], "targets": ["n6"]},
      {"id": "e6", "sources": ["n4"], "targets": ["n6"]}
    ]
  }
</script>

Gnuplotโ€‹

using gnuplot-JS

Instead of using data-output attribute in the script element, the statement set output is used in the diagram syntax (see highlighted lines below).

Data files are also specified in the diagram syntax (see highlighted lines below). They are defined in script elements with the attribute type="application/diagram-gnuplot-file". The file name is specified in data-file attribute and either have inline content or linked to with a src attribute.

Example: (open in LiveCodes)

<div data-src="contour.svg"></div>
<script type="application/diagram-gnuplot">
  set terminal svg size 600,400 enhanced fname 'arial' fsize 10 butt solid
  set output 'contour.svg'
  set view 60, 30, 0.85, 1.1
  set samples 25, 25
  set isosamples 26, 26
  set contour base
  set cntrparam bspline
  set cntrparam levels auto 10
  set style data lines
  set title "3D gnuplot demo - contour of data grid plotting"
  set xlabel "X axis"
  set xrange [ 0.00000 : 15.0000 ] noreverse nowriteback
  set ylabel "Y axis"
  set yrange [ 0.00000 : 15.0000 ] noreverse nowriteback
  set zlabel "Z axis"
  set zlabel  offset character 1, 0, 0 font "" textcolor lt -1 norotate
  set zrange [ -1.20000 : 1.20000 ] noreverse nowriteback

  # "glass.dat" is defined below
  splot "glass.dat" using 1
</script>

<!--  data file -->
<script
  type="application/diagram-gnuplot-file"
  data-file="glass.dat"
  src="https://raw.githubusercontent.com/gnuplot/gnuplot/master/demo/glass.dat"
></script>

<!--  or inline data in a script block -->
<script type="application/diagram-gnuplot-file" data-file="another-file.dat">
  0.568000   0.000000  -0.911000
  0.518894   0.231026  -0.911000
  0.380066   0.422106  -0.911000
  0.175522   0.540200  -0.911000
  -0.059372   0.564888  -0.911000
</script>

Graphvizโ€‹

using @hpcc-js/wasm

The following layout engines are supported:

  • dot
  • neato
  • fdp
  • sfdp
  • circo
  • twopi
  • osage
  • patchwork

By default, the dot layout engine is used. To use a different engine add the attribute data-layout to the script element with the value of the required engine name, like this:

<script type="application/diagram-graphviz" data-layout="fdp" data-output="my-diagram">
  ...
</script>

Example: (open in LiveCodes)

<div data-src="flow-chart.svg"></div>
<script type="application/diagram-graphviz" data-output="flow-chart.svg">
  digraph G {
    node [shape=rect];

    subgraph cluster_0 {
      style=filled;
      color=lightgrey;
      node [style=filled,color=white];
      a0 -> a1 -> a2 -> a3;
      label = "Hello";
    }

    subgraph cluster_1 {
      node [style=filled];
      b0 -> b1 -> b2 -> b3;
      label = "World!";
      color=blue
    }

    start -> a0;
    start -> b0;
    a1 -> b3;
    b2 -> a3;
    a3 -> a0;
    a3 -> end;
    b3 -> end;

    start [shape=Mdiamond];
    end [shape=Msquare];
  }
</script>

Mermaidโ€‹

Example: (open in LiveCodes)

<div data-src="class-diagram.svg"></div>
<script type="application/diagram-mermaid" data-output="class-diagram.svg">
  classDiagram
  Class01 <|-- AveryLongClass : Cool
  Class03 *-- Class04
  Class05 o-- Class06
  Class07 .. Class08
  Class09 --> C2 : Where am i?
  Class09 --* C3
  Class09 --|> Class07
  Class07 : equals()
  Class07 : Object[] elementData
  Class01 : size()
  Class01 : int chimp
  Class01 : int gorilla
  Class08 <--> C2: Cool label
</script>

Nomnomlโ€‹

Example: (open in LiveCodes)

<div data-src="nomnoml.svg"></div>
<script type="application/diagram-nomnoml" data-output="nomnoml.svg">
  [Pirate|eyeCount: Int|raid();pillage()|
    [beard]--[parrot]
    [beard]-:>[foul mouth]
  ]

  [<table>mischief | bawl | sing || yell | drink]

  [<abstract>Marauder]<:--[Pirate]
  [Pirate]- 0..7[mischief]
  [jollyness]->[Pirate]
  [jollyness]->[rum]
  [jollyness]->[singing]
  [Pirate]-> *[rum|tastiness: Int|swig()]
  [Pirate]->[singing]
  [singing]<->[rum]
</script>

Pintoraโ€‹

Pintora config object can be specified in custom settings, under the key pintora.

Example Custom Settings:

{
  "pintora": {
    "themeConfig": {
      "theme": "dark"
    }
  }
}

Example: (open in LiveCodes)

<div data-src="pintora.svg"></div>
<script type="application/diagram-pintora" data-output="pintora.svg">
  sequenceDiagram
    Frida-->>Georgia: Flowers are beautiful
    @note over Frida,Georgia: Painters
    @note right of Georgia: Right
    @note left of Georgia
    multiline
    note
    @end_note
</script>

Plotlyโ€‹

The diagram syntax is a JSON object with data and layout properties (see Plotly reference).

Please note that the output is a non-interactive SVG element or image. The plotly library is not loaded in the result page, so any JavaScript functionality is not available.

Example: (open in LiveCodes)

<div data-src="plotly.svg"></div>
<script type="application/diagram-plotly" data-output="plotly.svg">
  {
    "data": [
      {
        "y": [
          0.2,
          0.2,
          0.6,
          1,
          0.5,
          0.4,
          0.2,
          0.7,
          0.9,
          0.1,
          0.5,
          0.3
        ],
        "x": [
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 2",
          "day 2",
          "day 2",
          "day 2",
          "day 2",
          "day 2"
        ],
        "name": "kale",
        "marker": {
          "color": "#3D9970"
        },
        "type": "box"
      },
      {
        "y": [
          0.6,
          0.7,
          0.3,
          0.6,
          0,
          0.5,
          0.7,
          0.9,
          0.5,
          0.8,
          0.7,
          0.2
        ],
        "x": [
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 2",
          "day 2",
          "day 2",
          "day 2",
          "day 2",
          "day 2"
        ],
        "name": "radishes",
        "marker": {
          "color": "#FF4136"
        },
        "type": "box"
      },
      {
        "y": [
          0.1,
          0.3,
          0.1,
          0.9,
          0.6,
          0.6,
          0.9,
          1,
          0.3,
          0.6,
          0.8,
          0.5
        ],
        "x": [
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 1",
          "day 2",
          "day 2",
          "day 2",
          "day 2",
          "day 2",
          "day 2"
        ],
        "name": "carrots",
        "marker": {
          "color": "#FF851B"
        },
        "type": "box"
      }
    ],
    "layout": {
      "yaxis": {
        "title": "normalized moisture",
        "zeroline": false
      },
      "boxmode": "group"
    }
  }
</script>

Svgbobโ€‹

Example: (open in LiveCodes)

<div data-src="svgbob.svg"></div>
<script type="application/diagram-svgbob" data-output="svgbob.svg">
  o-> Graphics Diagram

     0       3                          P *
      *-------*      +y                    \
   1 /|    2 /|       ^                     \
    *-+-----* |       |                v0    \       v3
    | |4    | |7      | โ—„โ•ฎ               *----\-----*
    | *-----|-*     โคน +-----> +x        /      v X   \
    |/      |/       / โคด               /        o     \
    *-------*       v                 /                \
   5       6      +z              v1 *------------------* v2
</script>

Vegaโ€‹

The diagram syntax is Vega JSON specification.

Please note that the output is a non-interactive SVG element or image. The Vega library is not loaded in the result page, so any JavaScript functionality is not available.

Example: (open in LiveCodes)

<div data-src="vega.svg"></div>
<script
  type="application/diagram-vega"
  data-output="vega.svg"
  src="https://vega.github.io/vega/examples/stacked-bar-chart.vg.json"
></script>

VegaLiteโ€‹

The diagram syntax is Vega-Lite View JSON Specification.

Please note that the output is a non-interactive SVG element or image. The Vega-Lite library is not loaded in the result page, so any JavaScript functionality is not available.

Example: (open in LiveCodes)

<div data-src="vega-lite.svg"></div>
<script
  type="application/diagram-vega-lite"
  data-output="vega-lite.svg"
  src="https://vega.github.io/vega-lite/examples/sequence_line_fold.vl.json"
></script>

WaveDromโ€‹

The diagram syntax is WaveJSON format.

Example: (open in LiveCodes)

<div data-src="wavedrom.svg"></div>
<script type="application/diagram-wavedrom" data-output="wavedrom.svg">
  { signal : [
    { name: "clk",  wave: "p......" },
    { name: "bus",  wave: "x.34.5x",   data: "head body tail" },
    { name: "wire", wave: "0.1..0." },
  ]}
</script>
Sponsors