Flowy

The minimal javascript library to create flowcharts

Diagram / Flow chartDrag and drop
alyssaxuu/flowy

README


Flowy



Demo

A javascript library to create pretty flowcharts with ease ✨

Dribbble | Twitter | Live demo


Flowy makes creating WebApps with flowchart functionality an incredibly simple task. Build automation software, mind mapping tools, or simple programming platforms in minutes by implementing the library into your project.

You can support this project (and many others) through GitHub Sponsors! ❤️


Made by Alyssa X

Table of contents

- Features
- Installation
- Running Flowy
    - Initialization
    - Example
- Callbacks
- On grab
- On release
- On snap
- On rearrange
- Methods
    - Get the flowchart data
    - Import the flowchart data
    - Delete all blocks


Features

Currently, Flowy supports the following:

- [x] Responsive drag and drop
- [x] Automatic snapping
- [x] Automatic scrolling
- [x] Block rearrangement
- [x] Delete blocks
- [x] Automatic block centering
- [x] Conditional snapping
- [x] Conditional block removal
- [x] Import saved files
- [x] Mobile support
- [x] Vanilla javascript (no dependencies)
- [ ] npm install
You can suggest new features here

Installation

Adding Flowy to your WebApp is incredibly simple:

1.  Link  flowy.min.js  and  flowy.min.css  to your project. Through jsDelivr:
  1. ``` html
  2. <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/alyssaxuu/flowy/flowy.min.css"> 
  3. <script src="https://cdn.jsdelivr.net/gh/alyssaxuu/flowy/flowy.min.js"></script>
  4. ```
2. Create a canvas element that will contain the flowchart (for example, `
`)3. Create the draggable blocks with the `.create-flowy` class (for example, `
Grab me
`)

Running Flowy


Initialization

  1. ``` js
  2. flowy(canvas, ongrab, onrelease, onsnap, onrearrange, spacing_x, spacing_y);
  3. ```

Parameter | Type | Description
   canvas | javascript DOM element | The element that will contain the blocks
   ongrab | function (optional) |  Function that gets triggered when a block is dragged
   onrelease | function (optional) |  Function that gets triggered when a block is released
   onsnap | function (optional) |  Function that gets triggered when a block snaps with another one
   onrearrange | function (optional) |  Function that gets triggered when blocks are rearranged
   spacing_x | integer (optional) |  Horizontal spacing between blocks (default 20px)
   spacing_y | integer (optional) |  Vertical spacing between blocks (default 80px)

To define the blocks that can be dragged, you need to add the class .create-flowy

Example

HTML
  1. ``` html
  2. <div class="create-flowy">The block to be dragged</div>
  3. <div id="canvas"></div>
  4. ```
Javascript
  1. ``` js
  2. var spacing_x = 40;
  3. var spacing_y = 100;
  4. // Initialize Flowy
  5. flowy(document.getElementById("canvas"), onGrab, onRelease, onSnap, onRearrange, spacing_x, spacing_y);
  6. function onGrab(block){
  7. // When the user grabs a block
  8. }
  9. function onRelease(){
  10. // When the user releases a block
  11. }
  12. function onSnap(block, first, parent){
  13. // When a block snaps with another one
  14. }
  15. function onRearrange(block, parent){
  16. // When a block is rearranged
  17. }
  18. ```

Callbacks

In order to use callbacks, you need to add the functions when initializing Flowy, as explained before.

On grab

  1. ``` js
  2. function onGrab(block){
  3. // When the user grabs a block
  4. }
  5. ```
Gets triggered when a user grabs a block with the class create-flowy

Parameter | Type | Description
   block | javascript DOM element | The block that has been grabbed
  

On release

  1. ``` js
  2. function onRelease(){
  3. // When the user lets go of a block
  4. }
  5. ```
Gets triggered when a user lets go of a block, regardless of whether it attaches or even gets released in the canvas.

On snap

  1. ``` js
  2. function onSnap(block, first, parent){
  3. // When a block can attach to a parent
  4. return true;
  5. }
  6. ```
Gets triggered when a block can attach to another parent block. You can either prevent the attachment, or allow it by using return true;

Parameter | Type | Description
   block | javascript DOM element | The block that has been grabbed
   first | boolean | If true, the block that has been dragged is the first one in the canvas
   parent | javascript DOM element | The parent the block can attach to
  

On rearrange

  1. ``` js
  2. function onRearrange(block, parent){
  3. // When a block is rearranged
  4. return true;
  5. }
  6. ```
Gets triggered when blocks are rearranged and are dropped anywhere in the canvas, without a parent to attach to. You can either allow the blocks to be deleted, or prevent it and thus have them re-attach to their previous parent using return true;

Parameter | Type | Description
   block | javascript DOM element | The block that has been grabbed
   parent | javascript DOM element | The parent the block can attach to
  

Methods

Get the flowchart data

  1. ``` js
  2. // As an object
  3. flowy.output();
  4. // As a JSON string
  5. JSON.stringify(flowy.output());
  6. ```
The JSON object that gets outputted looks like this:
  1. ``` json
  2. {
  3. "html": ,
  4. "blockarr": [],
  5. "blocks": [
  6.   {
  7.    "id": 1,
  8.    "parent": 0,
  9.    "data": [
  10.     {
  11.     "name": "blockid",
  12.     "value": "1"
  13.     }
  14.    ],
  15.    "attr": [
  16.     {
  17.     "id": "block-id",
  18.     "class": "block-class"
  19.     }
  20.    ]
  21.   }
  22. ]
  23. }
  24. ```

Here's what each property means:

Key | Value type | Description
   html | string | Contains the canvas data
   blockarr | array | Contains the block array generated by the library (for import purposes)  
   blocks | array | Contains the readable block array
   id | integer | Unique value that identifies a block
   parent | integer |  The id of the parent a block is attached to (-1 means the block has no parent)
   data | array of objects |  An array of all the inputs within a certain block
   name | string |  The name attribute of the input
   value | string |  The value attribute of the input
   attr | array of objects |  Contains all the data attributes of a certain block

Import the flowchart data

  1. ``` js
  2. flowy.import(output)
  3. ```
Allows you to import entire flowcharts initially exported using the previous method, flowy.output()

Parameter | Type | Description
   output | javascript DOM element | The data from flowy.output()
  

Warning


This method accepts raw HTML and does not sanitize it, therefore this method is vulnerable to XSS. The _only_ safe use for this method is when the input isabsolutely trusted, if the input is _not_ to be trusted the use this method can introduce a vulnerability in your system.

Delete all blocks

To remove all blocks at once use:
  1. ``` js
  2. flowy.deleteBlocks()
  3. ```
Currently there is no method to individually remove blocks. The only way to go about it is by splitting branches manually.
#
Feel free to reach out to me through email at hi@alyssax.com or on Twitter if you have any questions or feedback! Hope you find this useful 💜