From f2c802500a7623c20b986aa467644ee7871658f0 Mon Sep 17 00:00:00 2001 From: Klemek Date: Sat, 13 Jul 2019 16:20:35 +0200 Subject: [PATCH] more docs --- README.md | 129 +++++++++++++++++++++++++++++++++++++++++++++-- localtests.js | 112 ---------------------------------------- src/rendering.js | 21 ++++++-- 3 files changed, 142 insertions(+), 120 deletions(-) delete mode 100644 localtests.js diff --git a/README.md b/README.md index db4b85e..e175442 100644 --- a/README.md +++ b/README.md @@ -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) - -## Install +* [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: ![sample](sample.png) @@ -119,4 +145,99 @@ Will produce the following diagram : ``` +## 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) \ No newline at end of file diff --git a/localtests.js b/localtests.js deleted file mode 100644 index cadf613..0000000 --- a/localtests.js +++ /dev/null @@ -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'}); diff --git a/src/rendering.js b/src/rendering.js index 5fcd7e4..4ee5e31 100644 --- a/src/rendering.js +++ b/src/rendering.js @@ -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, } } };