more docs
This commit is contained in:
Klemek
@@ -5,6 +5,22 @@
|
||||
# (WIP) fa-diagrams
|
||||
## SVG diagrams built from Font-Awesome icons
|
||||
|
||||
## RoadMap to v1
|
||||
|
||||
* [x] Font-Awesome paths scrapping in build
|
||||
* [x] Node placing with links
|
||||
* [x] SVG output
|
||||
* [x] Node's icon rendering
|
||||
* [x] Simple links rendering
|
||||
* [ ] Dashed links rendering
|
||||
* [ ] Colors
|
||||
* [ ] Sub-elements
|
||||
* [ ] More options
|
||||
* [ ] PNG output
|
||||
* [ ] Unit testing
|
||||
|
||||
## Summary
|
||||
|
||||
* [Install](#install)
|
||||
* [CDN](#cdn)
|
||||
* [Static scripts](#static-scripts)
|
||||
@@ -13,8 +29,18 @@
|
||||
* [Usage](#usage)
|
||||
* [Node module](#node-module)
|
||||
* [Html script](#html-script)
|
||||
* [API](#api)
|
||||
* [`options`](#options)
|
||||
* [`nodes`](#nodes)
|
||||
* [`links`](#links)
|
||||
* [Sub-elements](#sub-elements)
|
||||
* [More info](#more-info)
|
||||
* [Icon names](#icon-names)
|
||||
* [Link types](#link-types)
|
||||
* [Examples](#examples)
|
||||
|
||||
## Install
|
||||
*[back to top](#top)*
|
||||
|
||||
### Static scripts
|
||||
|
||||
@@ -58,6 +84,7 @@ node build.sh
|
||||
```
|
||||
|
||||
## Usage
|
||||
*[back to top](#top)*
|
||||
|
||||
### Node module
|
||||
|
||||
@@ -83,7 +110,6 @@ const data = {
|
||||
],
|
||||
links: [
|
||||
{
|
||||
type: 'arrow',
|
||||
from: 'node1',
|
||||
to: 'node2',
|
||||
bottom: {text: 'Hello World!'}
|
||||
@@ -94,7 +120,7 @@ const data = {
|
||||
const svg = faDiagrams.compute(data); // string containing xml data
|
||||
```
|
||||
|
||||
Will produce the following diagram :
|
||||
Will produce the following diagram:
|
||||
|
||||
|
||||
|
||||
@@ -119,4 +145,99 @@ Will produce the following diagram :
|
||||
</html>
|
||||
```
|
||||
|
||||
## API
|
||||
*[back to top](#top)*
|
||||
|
||||
**You must pass as argument an object containing 3 keys:**
|
||||
* [`options`](#options)
|
||||
* [`nodes`](#nodes)
|
||||
* [`links`](#links)
|
||||
|
||||
### `options`
|
||||
|
||||
| Key (`/subkey`) | Default value | Info |
|
||||
| --- | --- | --- |
|
||||
| `placing/max-link-length` | 3 | maximum stretching of links between nodes |
|
||||
| `placing/diagonals` | `true` | allow diagonal links to be made |
|
||||
| `rendering/beautify` | `false` | output a readable SVG file |
|
||||
| `rendering/scale` | 128 | (in pixels) final icons size |
|
||||
| `rendering/color` | `black` | color of all elements |
|
||||
| `rendering/h-spacing` | 1.3 | how width is stretched comparing to height |
|
||||
| `rendering/icons/scale` | 1 | default scaling of icons (might be redefined in node definition) |
|
||||
| `rendering/links/scale` | 1 | default scaling of links (might be redefined in link definition) |
|
||||
| `rendering/links/size` | 0 | forced size/length of the links (0 means it will be computed from the distance between the nodes) (might be redefined in link definition) |
|
||||
| `rendering/texts/font` | `'Arial'` | font family of the texts (might be redefined in sub-elements definition) |
|
||||
| `rendering/texts/font-size` | 20 | font size of the texts (might be redefined in sub-elements definition) |
|
||||
| `rendering/texts/font-style` | `'normal'` | font style of the texts (see [Font styles](#font-styles)) (might be redefined in sub-elements definition) |
|
||||
|
||||
### `nodes`
|
||||
|
||||
Array of object as following:
|
||||
|
||||
| Key | Type | Required | Info |
|
||||
| --- | --- | --- | --- |
|
||||
| **`name`** | string | **yes** | used in links to reference nodes |
|
||||
| **`icon`** | string | **yes** | name of the Font-Awesome icon of the node (see [Icon names](#icon-names)) |
|
||||
| `top`, `bottom`, `left`, `right` | string or object | no | see [Sub-elements](#sub-elements) |
|
||||
| `color` | string | no | redefined the color |
|
||||
| `scale` | number | no | redefine this node icon scale |
|
||||
| `x`, `y` | number | no | force the position of this node |
|
||||
|
||||
### `links`
|
||||
|
||||
Array of object as following:
|
||||
|
||||
| Key | Type | Required | Info |
|
||||
| --- | --- | --- | --- |
|
||||
| **`from`** | string | **yes** | source node name |
|
||||
| **`to`** | string | **yes** | destination node name |
|
||||
| `type` | string | no | link's appearance (see [Link types](#link-types)) |
|
||||
| `top`, `bottom` | string or object | no | see [Sub-elements](#sub-elements) |
|
||||
| `color` | string | no | redefined the color |
|
||||
| `scale` | number | no | redefine this link scale |
|
||||
| `size` | number | no | forced size/length of the link |
|
||||
|
||||
### Sub-elements
|
||||
|
||||
Elements meant to be drawn along-side a node/link.
|
||||
There are two types: text and icons
|
||||
|
||||
### Texts
|
||||
|
||||
You can **just enter a string** to be considered a text but you can define a text with more options as following:
|
||||
|
||||
| Key | Type | Required | Info |
|
||||
| --- | --- | --- | --- |
|
||||
| **`text`** | string | **yes** | value of your text |
|
||||
| `color` | string | no | redefined the color |
|
||||
| `font` | string | no | redefine the font family |
|
||||
| `font-size` | number | no | redefine the font size |
|
||||
| `font-style` | string | no | redefine the font style (see [Font styles](#font-styles)) |
|
||||
|
||||
### Icons
|
||||
|
||||
You can define a relative icon with the following:
|
||||
|
||||
| Key (`/subkey`) | Type | Required | Info |
|
||||
| --- | --- | --- | --- |
|
||||
| **`icon`** | string | **yes** | name of the Font-Awesome icon of the sub-element (see [Icon names](#icon-names)) |
|
||||
| `color` | string | no | redefined the color |
|
||||
|
||||
## More info
|
||||
*[back to top](#top)*
|
||||
|
||||
### Icon names
|
||||
|
||||
(soon)
|
||||
|
||||
### Link types
|
||||
|
||||
(soon)
|
||||
|
||||
### Font styles
|
||||
|
||||
(soon)
|
||||
|
||||
## Examples
|
||||
*[back to top](#top)*
|
||||
(soon)
|
||||
-112
@@ -1,112 +0,0 @@
|
||||
const faDiagrams = require('./src/index');
|
||||
const fs = require('fs');
|
||||
|
||||
/*const data = {
|
||||
options: {
|
||||
font: 'Courier New'
|
||||
},
|
||||
nodes: [
|
||||
{
|
||||
name: 'node1',
|
||||
icon: 'server',
|
||||
bottom: {text: 'myserver' },
|
||||
top: {icon: 'node'}
|
||||
},
|
||||
{
|
||||
name: 'node2',
|
||||
icon: 'globe',
|
||||
bottom: {text: 'world'}
|
||||
}
|
||||
],
|
||||
links: [
|
||||
{
|
||||
type: 'arrow',
|
||||
from: 'node1',
|
||||
to: 'node2',
|
||||
direction: 'right',
|
||||
bottom: {text: 'Hello World!'}
|
||||
}
|
||||
]
|
||||
};*/
|
||||
|
||||
const data = {
|
||||
options: {
|
||||
rendering: {
|
||||
beautify: true
|
||||
},
|
||||
placing: {
|
||||
diagonals: true
|
||||
}
|
||||
},
|
||||
nodes: [
|
||||
{
|
||||
name: '1',
|
||||
icon: 'circle',
|
||||
},
|
||||
{
|
||||
name: '2',
|
||||
icon: 'circle'
|
||||
},
|
||||
{
|
||||
name: '3',
|
||||
icon: 'circle'
|
||||
},
|
||||
{
|
||||
name: '4',
|
||||
icon: 'circle'
|
||||
},
|
||||
{
|
||||
name: '5',
|
||||
icon: 'circle'
|
||||
},
|
||||
{
|
||||
name: '6',
|
||||
icon: 'circle'
|
||||
},
|
||||
],
|
||||
links: [
|
||||
{from: '1', to: '2', direction: 'right', type: ''},
|
||||
{from: '1', to: '3', direction: 'down', type: ''},
|
||||
{from: '3', to: '4', direction: 'right', type: ''},
|
||||
{from: '4', to: '5', direction: 'up', type: 'double'},
|
||||
{from: '3', to: '6', direction: 'left', type: ''}
|
||||
]
|
||||
};
|
||||
|
||||
fs.writeFileSync('out.svg', faDiagrams.compute(data), {encoding: 'utf-8'});
|
||||
|
||||
const rendering = require('./src/rendering')({
|
||||
'beautify': false,
|
||||
'scale': 1,
|
||||
'h-spacing': 1,
|
||||
'icons': {
|
||||
'scale': 0.1
|
||||
},
|
||||
'links': {
|
||||
'scale': 1
|
||||
},
|
||||
});
|
||||
|
||||
const g = [];
|
||||
|
||||
let y = 0;
|
||||
|
||||
for (let i = 0; i < 20; i++) {
|
||||
if (i % 5 === 0)
|
||||
y = 0;
|
||||
['', 'double', 'line'].forEach(type => {
|
||||
g.push({
|
||||
'_attributes': {
|
||||
'transform': `translate(${Math.pow(Math.floor(i / 5), 1.6) * 720} ${256 * (y++)})`
|
||||
},
|
||||
'path': {
|
||||
'_attributes': {
|
||||
'd': rendering.getLinkPath(type, (i + 1) / 5)
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
}
|
||||
|
||||
fs.writeFileSync('out2.svg', rendering.toXML({g: g}, {w: 7000, h: 256 * 16}), {encoding: 'utf-8'});
|
||||
+17
-4
@@ -30,8 +30,10 @@ const DEFAULT_OPTIONS = {
|
||||
'scale': 1
|
||||
},
|
||||
'links': {
|
||||
'scale': 1
|
||||
'scale': 1,
|
||||
'size': 0
|
||||
},
|
||||
'font': 'Arial' // https://websitesetup.org/web-safe-fonts-html-css/
|
||||
};
|
||||
|
||||
const DEFAULT_SCALE = 0.4;
|
||||
@@ -78,8 +80,16 @@ module.exports = (options = DEFAULT_OPTIONS) => {
|
||||
return null;
|
||||
},
|
||||
|
||||
/**
|
||||
* Create the correct path from the type and width
|
||||
* @param {string} type
|
||||
* @param {number} width
|
||||
* @return {string|null}
|
||||
*/
|
||||
getLinkPath: (type, width) => {
|
||||
switch (type) {
|
||||
case 'none':
|
||||
return null;
|
||||
case 'line':
|
||||
return `M12 216c-6.627 0-12 5.373-12 12v56c0 6.627 5.373 12 12 12h${width * 512 - 24}c6.627 0 12 -5.373 12 -12v-56c0 -6.627 -5.373 -12 -12 -12z`;
|
||||
case 'double':
|
||||
@@ -154,7 +164,10 @@ module.exports = (options = DEFAULT_OPTIONS) => {
|
||||
|
||||
const size = Math.sqrt(Math.pow((dst.x - src.x) * options['h-spacing'], 2) + Math.pow(dst.y - src.y, 2));
|
||||
|
||||
const path = self.getLinkPath(link.type, link['size'] || size);
|
||||
const path = self.getLinkPath(link.type, link['size'] || options['links']['size'] || size);
|
||||
|
||||
if (!path)
|
||||
return;
|
||||
|
||||
const scale = (link['scale'] || options['links']['scale']) * DEFAULT_SCALE;
|
||||
const group = {
|
||||
@@ -188,8 +201,8 @@ module.exports = (options = DEFAULT_OPTIONS) => {
|
||||
'_attributes': {
|
||||
'xmlns': 'http://www.w3.org/2000/svg',
|
||||
'viewBox': `0 0 ${bounds.w * options['h-spacing']} ${bounds.h}`,
|
||||
'width': bounds.w * options['h-spacing'] * options['scale'],
|
||||
'height': bounds.h * options['scale'],
|
||||
'width': bounds.w * options['h-spacing'] * options['scale'] / DEFAULT_SCALE,
|
||||
'height': bounds.h * options['scale'] / DEFAULT_SCALE,
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user