Skip to main content

Flowchart Builder

This page provides technical details for how to integrate the Flowchart Builder into your applications.

Imports

The Flowchart Builder ships in the package @jsplumb-components/flowchart. To use the vanilla component, you'll need an entry like this in your package.json:

{
"dependencies":{
"@jsplumb-components/flowchart":"x.x.x"
}
}

If you're using Angular, you'll also want to take a look at the Angular wrapper documentation page.

If you're using React, you'll also want to take a look at the React wrapper documentation page.


Setup

The Flowchart Builder consists of 3 parts:

  • the builder canvas
  • the palette from which new nodes can be dragged onto the canvas
  • the object inspector

Each of these parts is rendered to a separate element and it is up to you where in your page you want these elements to reside. It is also possible to create a flowchart builder that has no palette or inspector attached.

Basic setup

Here, we create a flowchart builder and specify an element for the palette and also for an inspector. This example uses ES6; examples for ES5 and Angular are given below.

import { newInstance } from "@jsplumb-components/flowchart"

const builderContainer = document.getElementById("some-builder-container")
const paletteContainer = document.getElementById("some-palette-container")
const inspectorContainer = document.getElementById("some-inspector-container")

const flowchartBuilder = newInstance({
container:builderContainer,
palette:{
container:paletteContainer
},
inspector:{
container:inspectorContainer
}
})


Options

These are the options that can be passed in to the newInstance method:

Home > @jsplumb-components/flowchart > FlowchartBuilderOptions

FlowchartBuilderOptions interface

Options for the flowchart builder

Signature:

export interface FlowchartBuilderOptions 

Properties

PropertyTypeDescription
colors?Array<string>(Optional) Optional list of colors to make available for quick pick in the inspector, if the inspector is enabled. These colours must be in CSS hex format, eg #FFEEDD, or with an alpha value, #FFEEDD56. No other format is supported.
containerHTMLElementThe element into which to draw the flowchart builder. Required.
data?FlowchartBuilderData(Optional) Optional data to load when the component is first created.
grid?GridOptions(Optional) Optional spec for the grid. Default is 20x20, with a visible grid, no border.
inspector?InspectorConfiguration(Optional) Optional object inspector setup. If you do not provide this, no inspector will be registered.
lineStyles?Array<{ id: string; svg: string; }>(Optional)
messages?FlowchartBuilderMessages(Optional) Optional set of messages to use. The default messages are in English. You can use this to override the English defaults, or to supply messages in a different language.
onError?(msg: string) => any(Optional) Handler for error messages shown to the user.
onMaybeDeleteEdge?(edge: FlowchartEdge) => boolean(Optional) Optional function which can be used to confirm deletion of an edge
onMaybeDeleteNode?(node: FlowchartVertex) => boolean(Optional) Optional function which can be used to confirm deletion of a node
palette?PaletteConfiguration(Optional) Optional object palette setup. If you do not provide this, no object palette will be registered.
readOnly?boolean(Optional) When true, the flowchart is presented in read only mode: zoom and pan are disabled, and no inspector or object palette will be rendered.
shapeSets?Array<ShapeSet>(Optional) Optional list of extra shape sets for the widget to support.
undoRedo?UndoRedoOptions(Optional) Options for undo/redo.
useDefaultShapeSet?boolean(Optional) Defaults to true, meaning that the default shape set will always be used, even if you provide a list of shape sets. If you set this to false, only the shapes sets you provide will be available for use.
wheelPan?boolean(Optional) When true, the mouse wheel will pan the canvas. Defaults to false.
wheelZoom?boolean(Optional) When true (which is the default), the mouse wheel will zoom the canvas. When false, the mouse wheel will pan the canvas.
wheelZoomMetaKey?boolean(Optional) When true, if wheelZoom is false, the user can hold down their OS's meta key (CMD in mac, Ctrl key in windows/linux) to make the mouse wheel control the zoom instead of the pan.

Methods

There is a full set of methods available on the flowchart builder for you to control it programmatically.

Home > @jsplumb-components/flowchart > FlowchartBuilder

FlowchartBuilder interface

The flowchart builder widget.

Signature:

export interface FlowchartBuilder 

Methods

MethodDescription
addNode(data)Adds a node with the given data.
clear()Clears the current flowchart dataset.
deselect(element)Remove the specified element from the list of elements that are selected.
exportData()Exports the current flowchart dataset.
exportData()Exports the current dataset.
loadData(data, onload)Loads the given flowchart, first clearing the dataset.
loadUrl(url, onload)Loads a flowchart from the specified url. The response from the URL is expected to be JSON, in FlowchartBuilderData format.
redo()Performs a redo of the last undone action (if any).
removeNode(node)Removes the given node from the dataset
select(element, replaceSelection)Adds the specified element to the elements that are selected, optionally replacing the selection with just this element.
undo()Performs an undo of the last action.
zoomToFit()Zoom the display so all content fits in the viewport.
zoomToFitIfNecessary()Zoom the display so all content fits in the viewport, but don't adjust the zoom if all the content is already visible.

CSS

The Flowchart Builder ships with a defaults stylesheet:

  • jsplumb.components.flowchart.css

You should include this in your CSS when using the flowchart builder in your code, at least until you get to the point that you have provided all the necessary styles in your own stylesheets.

Builder canvas

ClassPurpose
jtk-component-flowchartAssigned to the Flowchart Builder's root element
jtk-flowchart-builder-objectAssigned to each object in the flowchart palette
jtk-flowchart-builder-object-{{type}}Assigned to objects of type {{type}} in the flowchart palette

Palette

ClassPurpose
jtk-flowchart-builder-paletteAssigned to the palette container
jtk-flowchart-builder-palette-setAssigned to an icon set in the palette

Inspector

ClassPurpose
jtk-flowchart-builder-inspectorAssigned to an inspector container
jtk-flowchart-builder-inspector-headingAssigned to the subject headings in an inspector container

Undo/redo

The flowchart builder supports undo/redo to an arbitrary depth. There are two ways to use undo/redo

  • call the undo() or redo() method on an instance of the flowchart builder
  • provide elements to the flowchart builder's constructor that, when clicked, should cause undo() or redo() to be invoked.

Providing undo/redo buttons

import { newInstance } from "@jsplumb-components/flowchart"

const flowchart = newInstance({
container:document.getElementById("container"),
undoRedo:{
undo:document.querySelector("[data-action='undo']"),
redo:document.querySelector("[data-action='redo']")
}
})

Internationalization

The flowchart builder fully supports internationalization by allowing you to provide your own message bundle. A message bundle is a map of strings, from keys to values, and in the flowchart builder the required keys are specified by the FlowchartBuilderMessages interface:

Home > @jsplumb-components/flowchart > FlowchartBuilderMessages

FlowchartBuilderMessages interface

Set of messages required by the Flowchart Builder component

Signature:

export interface FlowchartBuilderMessages extends Record<string, any> 

Extends: Record<string, any>

Properties

PropertyTypeDescription
"button.inspector.cancel"string
"button.inspector.commit"string
"confirm.delete.edge"stringShown to a user to confirm they wish to delete an edge. Defaults to "Delete Edge".
"inspector.line.style"string
"inspector.node.fill"stringShown in the node inspector next to the 'fill' field. Defaults to "Fill".
"inspector.node.height"stringShown in the node inspector next to the 'height' field. Defaults to "h".
"inspector.node.label"stringShown in the node inspector next to the 'label' field. Defaults to "Label".
"inspector.node.size"stringShown in the node inspector above the "width" and "height" fields. Defaults to "Size"
"inspector.node.width"stringShown in the node inspector next to the 'width' field. Defaults to "w".
"inspector.nothing.selected"stringShown in the node inspector when no object is selected. Defaults to "No object selected".
"palette.showAllShapeSets"string

You can supply your own messages via the messages parameter to the newInstance method:

import { newInstance } from "@jsplumb-components/flowchart"

const flowchart = newInstance({
container:someElement,
messages:{
"button.inspector.cancel":"ABORT!",
...etc
}
})


Grids

The flowchart builder offers support for constraining elements to a grid when dragging, and for display a customizable background grid. This is controlled via the grid option of the flowchart builder's constructor parameters:

Home > @jsplumb-components/flowchart > GridOptions

GridOptions interface

Definition of a grid - the width/height of each cell, whether or not to impose the grid on element dragging, whether or not to display the grid, grid display options.

Signature:

export interface GridOptions 

Properties

PropertyTypeDescription
autoShrink?boolean(Optional) Defaults to false, meaning that if a grid minimum is set and the content expands beyond the minimum and then subsequently contracts below it, the grid will shrink back to the declared minimum. Setting this to true will mean that the grid never shrinks back once it has grown. This applies to both axes.
cellHeightnumberHeight of each cell in the grid. Defaults to 50 pixels.
cellWidthnumberWidth of each cell in the grid. Defaults to 50 pixels.
dragOnGrid?boolean(Optional) whether or not the grid should be applied to element dragging. Defaults to true.
maxHeight?number(Optional) Grid's maximum height. Defaults to no maximum. When set, the grid is guaranteed to never span beyond -maxHeight / 2 in the negative y axis and maxHeight / 2 in the positive y axis.
maxWidth?number(Optional) Grid's maximum width. Defaults to no maximum. When set, the grid is guaranteed to never span beyond -maxWidth / 2 in the negative x axis and maxWidth / 2 in the positive x axis.
minHeight?number(Optional) Grid's minimum height. Defaults to no minimum. When set, the grid is guaranteed to span at least from -minHeight / 2 to minHeight / 2 in the y axis.
minorLinesPerCell?number(Optional) How many minor lines to show per cell. Defaults to 5.
minWidth?number(Optional) Grid's minimum width. Defaults to no minimum. When set, the grid is guaranteed to span at least from -minWidth / 2 to minWidth / 2 in the x axis.
showBorder?boolean(Optional) Draw a border around the grid. Defaults to false.
showGrid?boolean(Optional) Whether or not to show a visible grid background. Defaults to true.
showMinorLines?boolean(Optional) Whether or not to show minor lines in the grid. Defaults to true.

By default, the flowchart builder will use a 50x50 pixel grid for element dragging, and it will display a grid background without a border but with both major and minor lines. It is straightforward to change this setup, for instance perhaps you don't want to show the background grid at all:

import { newInstance } from "@jsplumb-components/flowchart"

const flowchart = newInstance({
container:someElement,
grid:{
showGrid:false
}
})

Or perhaps you want to show the grid but not force the elements to conform to it when dragging:

import { newInstance } from "@jsplumb-components/flowchart"

const flowchart = newInstance({
container:someElement,
grid:{
dragOnGrid:false
}
})

You can change the size of the grid with the cellWidth and cellHeight values:

import { newInstance } from "@jsplumb-components/flowchart"

const flowchart = newInstance({
container:someElement,
grid:{
cellWidth:150,
cellHeight:150
}
})

Demonstrations

There are 2 example repositories on Github that licensees and evaluators can clone in order to familiarise themselves with how to use the flowchart builder component:

We are currently working on Vue2 and Vue3 wrappers for the flowchart builder.


ES5 Usage

The flowchart builder package is registered in the browser using the global name jsPlumbFlowchartBuilder. To create an instance of the flowchart builder in ES5, you can do this:

var builderContainer = document.getElementById("some-builder-container"),
paletteContainer = document.getElementById("some-palette-container"),
inspectorContainer = document.getElementById("some-inspector-container");

var flowchartBuilder = jsPlumbFlowchartBuilder.newInstance({
container:builderContainer,
palette:{
container:paletteContainer
},
inspector:{
container:inspectorContainer
}
});

Once you have the flowchart builder instance, working with it is the same as shown in the various ES6 examples in the documentation and demonstrations.