@toothlessjs/diagram-drawer v1.1.9

Allows for creating diagrams from JSON files. Uses paper.js.

Install

$ npm install @toothlessjs/diagram-drawer

Usage

To render a diagram create StructureDrawer object, initialize it with canvas that diagram will be drawn on. Next, call init(dictionary) to initialize elements and connections inside it. Then render them on canvas using draw(). You also need to import paper.js script in html so that StructureDrawer can use it.

<script type="text/javascript" src="paper.js"></script>
<script>
  var canvas = document.getElementById("myCanvas");
  var dict = {...};
  structureDrawer = new StructureDrawer(canvas);
  structureDrawer.init(dict);
  structureDrawer.draw();
</script>

Here you can see example how to use it in practice.

Dictionary structure

Dictionary used in init() function must contain specific keys and their values:

• x_size - sets canvas width to this value
• y_size - sets canvas height to this value
• background_color - fills canvas with this color (string with #rgb notation i.e. "#00ff77"). If string is empty canvas won't be filled
• elements - dictionary that contains all points to be rendered. Each element inside dictionary is defined by another dictionary and the key functions as ID of the element
• connections - list of dictionaries that specify which points (elements) should be connected to each other

Elements attributes

After init() is called, StructureDrawer takes all defined elements and calculates their attributes needed for paper.js to render them. Attributes can be divided into those that define element position and those that define its appearance.

Appearance

The following attributes are used to specify appearance of the element:

• shape - string that can take three values: "rectangle" (default), "ellipse" and "text"

shape: rectangle	shape: ellipse	shape: text

• width - number
• height - number

Note: shape: text will override width and height attributes to the size of font.

• background_color - string in #rgb notation. If empty, background is transparent (default)
• border_width - number (1 by default)
• border_color - string in #rgb notation. If empty, border is transparent (default)
• text - string, text to display in the center of element
• text_color - string in #rgb notation. If empty, text is transparent (default)
• text_size - number (10 by default)
• copy - ID of other element that appearance attributes should be copied into this one. Attributes are copied first, then those specified are overwritten

To explain copy attribute, let's create new element with following attributes:

"original": {
  "width": 65
  "height": 45
  "background_color": "#afc"
  "border_color": "#f4a"
  "border_width": 2
  "text": "42"
  "text_color": "#f4a"
  "text_size": 30
}

Now, we will create similar element with different text color:

"copy": {
  "copy": "original"
  "text_color": "#fc9403"
}

Results:

Original	Copy

Positioning

The following attributes are used to specify element position:

• x - absolute x position on canvas (if position attribute is defined it acts more like an offset)
• y - absolute y position on canvas (if position attribute is defined it acts more like an offset)
• position - ID of other element. If element with specified ID exists, currently initialized element takes x and y values from it. If x and y attributes are also defined, they are added to copied position
• align - string with four possible values: top, bottom, left and right. If position attribute is defined, current element will be put next to element pointed by it

Some examples to better understand how positioning works:

	Without position	With position: orange
x: 0, y: 0
x: 20, y: 20

If x and y are equal to 0, element won't be rendered. This is useful when creating template elements (using copy attribute so you don't have to copy/paste attributes).

align attribute (with position: orange):

	align: top	align: right
x: 0, y: 0
x: 20, y: 20

Note: Use shape: text and align attributes to concatenate texts with each other.

Connections attributes

After StructureDrawer initializes all the elements, it goes to list of connections. Connections always connect centers of elements and end on their borders. Connection must have from and to attributes which consist of IDs of elements to be connected. Their appearance can be modified with following attributes:

• margin - positive number. Distance between border of the element and end of connection. 0 by default

margin: 0	margin: 10

• text - string - text that appears on connection
• text_color - string in #rgb notation. If empty text is transparent (default)
• text_size - number, 10 by default
• text_offset - number in range from 0 to 1. Defines text placement relative to the length of connection. 0.5 by default (center)

text_offset: 0.5	text_offset: 0.2

• text_height - number, distance between text and connection (10 by default)

text_height: 0	text_height: 20

• start_arrow - true / false. If true, an arrow will be drawn at the start of connection (false be default)
• end_arrow - true / false. If true, an arrow will be drawn at the end of the connection (false by default)

	start_arrow: false	start_arrow: true
end_arrow: false
end_arrow: true

• arrow_width - number, defines the length of the back of the arrows (10 by default)
• arrow_offset - number, defines how long arrows are (10 by default)

	arrow_width: 10	arrow_width: 20
arrow_offset: 10
arrow_offset: 20

• start_x_offset - number, shifts the start of connection on x axis (0 by default)
• start_y_offset - number, shifts the start of connection on y axis (0 by default)
• end_x_offset - number, shifts the end of connection on x axis (0 by default)
• end_y_offset - number, shifts the end of connection on y axis (0 by default)

	start_x_offset: 0	start_x_offset: 20
start_y_offset: 0
start_y_offset: 20

• segments - list of points (x and y) that connection has to go through
• smoothing_factor - number in range from 0 to 1. If segments exist, smoothens the curves. (0.2 by default)

Let's create two sets of segments:

[
  {
    "x": 20,
    "y": 80
  }
]

[
  {
    "x": 20,
    "y": 50
  },
  {
    "x": 80,
    "y": 50
  }
]

And combine them with different smoothing_factors:

	smoothing_factor: 0	smoothing_factor: 0.5
first segments set
second segments set

Known issues

Diagram won't render when two connected elements are overlapping.