DgrmJS

A library for creating SVG flow diagram editor

Diagram / Flow chartDrawingSVG
AlexeyBoiko/DgrmJSapp.dgrm.netdgrm

README

DgrmJS

Flow diagram editor dgrm.net | NPM

DgrmJS is a JavaScript library for creating SVG flow diagram editors.  
The main goal of the library is to set up workflows in BPM (Business Process Management) systems.

- Works on desktop and mobile
- Has no dependency
- 3.5 KB gzipped

diagram

Main idea

- Allow developers to use standard SVG objects and features to declaratively create shapes that will be used in the diagram.  
To create shape, developers should add special data- attributes to standard SVG markup. So any svg images can be used as a shape in a diagram.
- DgrmJS dispatch events, like ‘shape is selected’ or ‘shape is connecting to another shape’.  
Developers can use these events to implement their own logic, for example, make a JSON description of the workflow.

Apache-2.0 license

Free for any type of use. Including commercial projects.

Articles:  

JavaScript SVG diagram editor 6.5 times smaller than Bootstrap
JavaScript diagram editor that renders diagrams from PNG images (open source)")
JavaScript text editor for SVG
Flowchart editor UI
JavaScript: Zoom like in maps for SVG/HTML

How to use

See a minimalistic example - GitHub repository: DgrmJS Example.

Install

From npm:
  1. ```
  2. npm i dgrm
  3. ```

Simple shape

This is a circle shape:

  1. ``` html
  2. <svg id="diagram" style="touch-action: none;">
  3. <defs>
  4.   
  5.   <g data-templ="circle">
  6.    <circle ... />
  7.    <!-- inner named element,
  8.    we can use 'data-key' value as a key
  9.    in shapeAdd(...) method -->
  10.    <text data-key="text"></text>
  11.   </g>
  12. </defs>
  13. <g data-key="canvas"></g>
  14. </svg>
  15. <script type="module">
  16. import { svgDiagramCreate } from './diagram/svg-presenter/svg-diagram-factory.js';
  18. const diagram = svgDiagramCreate(document.getElementById('diagram'))
  20. // add shape to canvas
  21. diagram.shapeAdd({
  22.   // template name
  23.   // (value of the 'data-templ' attribute)
  24.   templateKey: 'circle',
  25.   position: { x: 120, y: 120 },
  26.   props: {
  27.    // inner svg element with 'data-key=text'
  28.    // will get 'textContent' value 'Title'
  29.    text: { textContent: 'Title' }
  30.   }
  31. });
  32. </script>
  33. ```

diagram.shapeAdd method add to canvas shape:
- created by template with name "circle"
- to position at point 120, 120
- props set
  - textContent of the inner element with data-key="text" to "Title"

This way you can set any attribute of any shape object.

Result is a draggable circle with "Title" text:

draggable shape

Add "out connectors" to shape

"Out connector" is an element from which you can draw out a connecting line.  
Add data-connect="out" to mark element as a out connector:

  1. ``` html
  2. <g data-templ="circle">
  3.     <circle ... />
  4.     <text data-key="text"></text>
  5.  
  6.     <!--
  7.         out connector
  8.         data-connect-point - point into shape where connector line starts
  9.         data-connect-dir - direction of connector line
  10.     -->
  11.     <circle
  12.         data-connect="out"
  13.         data-connect-point="60,0"
  14.         data-connect-dir="right" ...>
  15.     </circle>
  16. </g>
  17. ```
draggable shape

Add "in connectors" to shape

"In connector" is an element where you can connect a connection line to a shape.
  1. ``` html
  2. <g data-templ="circle">
  3.     <circle ... />
  4.     <text data-key="text"></text>
  5.  
  6.     <!--
  7.         out connector
  8.         data-connect-point - point into shape where connector line starts
  9.         data-connect-dir - direction of connector line
  10.     -->
  11.     <circle
  12.         data-connect="out"
  13.         data-connect-point="60,0"
  14.         data-connect-dir="right" ...>
  15.     </circle>
  16.  
  17.     <!--
  18.         in connector
  19.     -->
  20.     <circle
  21.         data-connect="in"
  22.         data-connect-point="-60,0"
  23.         data-connect-dir="left" ...>
  24.     </circle>
  25. </g>
  26. ```
draggable shape

Events

In this example:
- we subscribe to the select event
- update title of the selected shape

  1. ``` html
  2. <svg id="diagram" style="touch-action: none;">
  3.     <defs>
  4.         
  5.         <g data-templ="circle">
  6.             <circle ... />
  7.             <!-- inner named element,
  8.                 we can use 'data-key' value as a key
  9.                 in shapeAdd(...) method -->
  10.             <text data-key="text"></text>
  11.  
  12.             
  13.             <circle data-connect="out" ...></circle>
  14.             <circle data-connect="in" ...></circle>
  15.         </g>
  16.     </defs>
  17.     <g data-key="canvas"></g>
  18. </svg>
  19. <script type="module">
  20.     import { svgDiagramCreate } from './diagram/svg-presenter/svg-diagram-factory.js';
  21.  
  22.     const diagram = svgDiagramCreate(document.getElementById('diagram'))
  23.         // subscribe to 'select' event
  24.         .on('select', evt => {
  25.  
  26.             // update selected shape
  27.             evt.detail.target.update({
  28.                 props: {
  29.                     text: { textContent: 'New title' }
  30.                 }
  31.             });
  32.  
  33.         });
  34.  
  35.     // add shape to canvas
  36.     diagram.shapeAdd({
  37.         templateKey: 'circle',
  38.         position: { x: 120, y: 120 },
  39.         props: {
  40.             text: { textContent: 'Title' }
  41.         }
  42.     });
  43. </script>
  44. ```
draggable shape

Project structure


Diagram Engine (src/diagram folder)

src/diagram folder contains a diagram engine that can be used independently of other project files.  
This diagram engine contains all main features (all you need to implement diagram editor in your project):
- creating shapes with svg templates
- drag'n'drop
- connection of shapes
- diagram events

Diagram Extensions (src/diagram-extensions folder)

src/diagram-extensions folder contains additional features, like:
- export/import to/from png
- text editor
- editable shape base class
- and other

App (src/app folder)

src/app folder contains diagram builder dgrm.net.
- app`s shapes templates and styles
- json serialization
- ui elements

Documentation

Soon