Skip to main content

Plugins

The Surface component has a plugin architecture. Several pieces of functionality - the miniview, the lasso tool, the nudge buttons, the active filtering code, the concept of "ui states", and logical drag groups - are implemented as plugins, and the drawing tools have been refactored to conform to the plugin architecture. It is also possible to write your own.

Syntax

Plugins are declared in the render params for some surface:


import { MiniviewPlugin } from "@jsplumbtoolkit/browser-ui"

const surface = toolkitInstance.render(someElement, {
plugins:[
{
type:MiniviewPlugin.type,
options:{
container:someMiniviewElement
}
}
]
})

The syntax used to define them is the same as that used in 6.x to define anchors, connectors, endpoints and overlays:

{
type:string,
options:Record<string, any>
}

You can also just use the name of a plugin, if you don't need to configure it:


import { ActiveFilteringPlugin } from "@jsplumbtoolkit/browser-ui"

const surface = toolkitInstance.render(someElement, {
plugins:[
ActiveFilteringPlugin.type
]
})

Available Plugins

This is the full list of plugins that ship with the Toolkit:

Miniview

Provides the miniview widget. The Angular, Vue and React libraries declare this package as a peer dependency, since they contain a wrapper around this plugin. The Svelte integration does not provide a wrapper as one is not needed. Discussed in detail on this page.

Miniview - jsPlumb Toolkit, industry standard diagramming and rich visual UI Javascript library

Name: miniview

Interface MiniviewPluginOptions

Options for the miniview plugin.

Members

activeTracking?: boolean
Defaults to true, meaning the miniview actively updates as nodes/groups are dragged on the related surface. If this is set to false, the miniview only updates after mouseup.
clickToCenter?: boolean
Defaults to true, meaning a click on a node/group in the miniview will cause that node/group to be centered in the related surface.
collapsible?: boolean
Defaults to true, determines whether or not the miniview can be collapsed.
container: BrowserElement
Element to render into. When using a library integration you do not provide this.
elementFilter?:
Optional filter for elements to display. Defaults to undefined - all elements displayed.
enableWheelZoom?: boolean
Defauts to true, Whether or not to enable the wheel zoom.
suspended?: boolean
Defaults to false. Whether or not to suspend rendering after load.
typeFunction?:
Optional function to use to derive a type for each rendered node/group. This is written onto the corresponding element as the value of the data-jtk-miniview-type attribute, and can be useful for styling.
visible?: boolean
Defaults to true. Whether or not the miniview is initially visible.
wheelReverse?: boolean
Defaults to false. Whether or not to reverse the zoom direction in response to a wheel event.
wheelSensitivity?: number
Optional overide for how sensitive the wheel zoom should be.

Lasso

Provides the Lasso tool.

Name: lasso

Interface LassoPluginOptions

Members

filter?: string
Optional CSS3 filter identifying elements you do not want to lasso.
includeEdges?: boolean
Defaults to false. If true, edges are included in the lasso selection.
invert?: boolean
Defaults to false, meaning the lasso is drawn as a rectangle. If true, the lasso is drawn as a set of masks, with the lasso area drawn as a "hole" in the masks.
onEnd?: Function
Optional function to call when lasso selection ends.
onSelect?: Function
Optional function to call when one or more objects has been selected by the lasso.
onStart?: Function
Optional function to call when lasso selection starts.
selectionFilter?:
Optional filter that is passed every vertex/edge that the lasso would ordinarily select, and if this function returns false then the vertex/edge is not added to the selection

Pan Buttons

Provides the buttons around the perimeter of the Surface canvas that allow the user to nudge the pan.

Name: pan-buttons

Interface PanButtonsPluginOptions

Options for the pan buttons plugin.

Members

panDistance: number
Amount in pixels to pan the surface by when one of the buttons is pressed and released. Defaults to 50.
panRepeatDistance?: number
Amount in pixels to adjust pan by each time the timer fires. Defaults to 10.
panRepeatInterval?: number
Time in milliseconds between successive adjustment to the pan. Defaults to 60.
startPanTimeout?: number
Time in milliseconds after the mouse button is pressed before panning should start. Defaults to 150.

Drawing Tools

Provides the tools to assist in resizing nodes/groups. When the associated surface has a grid, this plugin will constrain node/group resizing so that the dimensions of the vertex are a multiple of the grid in each axis.

Drawing Tools - jsPlumb Toolkit, flowcharts, chatbots, bar charts, decision trees, mindmaps, org charts and more

The plugin automatically attaches resizing tools to any vertex that is added to a Toolkit's current selection, and removes the resizing tools when the vertex is removed from the selection. This behaviour can be changed by setting onDemand:true in the plugin options.

This plugin is discussed in detail on this page.

Name: drawingTools

Interface DrawingToolsPluginOptions

Options for the drawing tools plugin

Members

constrainGroups?: boolean
Defaults to true, meaning groups will not be shrunk to the point that one or more of their child vertices is no longer visible.
heightAttribute?: string
Attribute to use for vertex height - defaults to 'height'
ignoreGrid?: boolean
Defaults to false, meaning size changes conform to an underlying grid, if present
leftAttribute?: string
Attribute to use for vertex left position - defaults to 'left'
minimumHeight?: number
Minimum height the user can shrink a vertex to. Defaults to 30.
minimumWidth?: number
Minimum width the user can shrink a vertex to. Defaults to 30.
onDemand?: boolean
Defaults to false, meaning the drawing tool plugin switches on whenever a new vertex is selected.
onEdit?:
Optional callback invoked after an edit has occurred
topAttribute?: string
Attribute to use for vertex top position - defaults to 'top'
widthAttribute?: string
Attribute to use for vertex width - defaults to 'width'

Active Filtering

Provides the 'active filtering' code - the ability to disable drag targets programmatically when a new connection is dragged.

Name: activeFiltering

This plugin does not have any configurable options.

Usage

To use the active filtering plugin, you first need to provide a beforeConnect method to the constructor parameters of the Toolkit instance:

const tk = newInstance({
beforeConnect:(source:Vertex, target:Vertex) => {
// return true if the source and target are connectable,
// false otherwise.
}
})

then you declare the Active Filtering plugin in the render options:

toolkit.render(someElement, {
...
plugins:[
ActiveFilteringPlugin.type
]
})

UI States

Provides the ability to change the appearance of vertices by associating them to certain "states". Discussed in detail on this page.

Name: ui-states

Interface UiStatesPluginOptions

Options for the ui states plugin. Currently empty.

Members


Drag Groups

Provides the ability to manage logical drag groups.

Name: dragGroups

Interface DragGroupsPluginOptions

Options for the drag groups plugin.

Members


Snaplines

This plugin is discussed in detail on this page.

Snaplines - jsPlumb Toolkit, industry standard diagramming and rich visual UI Javascript library

Name: snaplines

Interface SnaplinesPluginOptions

Options for the snaplines plugin.

Members

enabled?: boolean
Defaults to true. If false, you can start the plugin in disabled mode.
showCenters?: boolean
Whether or not to show center snaplines. Defaults to true.
showEdges?: boolean
Whether or not to show edge snaplines. Defaults to true.
tolerance?: number
The tolerance either side of a snapline inside which an element must be before the snapline is activated. Defaults to 10 pixels (either side of the line).

Background

Name: background

Usage

The background plugin acts as a wrapper around one of a few subtypes. You need to supply the type of background you wish to use. Discussed in detail on this page.

Generated grid backgrounds

To use the generated grid background, set the type to GeneratedGridBackground.type:

plugins:[
{
type:BackgroundPlugin.type, // <-- add the wrapper
options:{
type:GeneratedGridBackground.type, // <-- set the subtype
... other options ...
}
}

]

The full list of options available for the generated grid background are:

Interface GeneratedGridBackgroundOptions

Options for the generated grid background. This background is still in beta as of 5.10.6.

Members

autoShrink?: boolean
Defaults to true, and instructs the grid that if the grid has grown beyond any minimum value set in either axis, if the content bounds subsequently shrink in that axis below the minimum, the grid should shrink back to the minimum. If you set this to false the grid will never shrink back to its minimum values once they have been exceeded.
dotRadius?: number
The radius for dots representing grid positions (when gridType id GridTypes.dotted). Defaults to 2.
grid?: Grid
The grid to use. This is optional; if you do not supply one the background will attempt to read the grid definition from the Surface. If that is also not set then a default grid of 50x50 pixels will be used.
gridType?:
Type of grid - lines or dots. Defaults to lines.
maxHeight?: number
The maximum height for the grid. The value you provided is divided by 2 and then the grid is guaranteed to never exceed the range of (-maxHeight / 2) - (maxHeight / 2). maxHeight takes precedence over minHeight.
maxWidth?: number
The maximum width for the grid. The value you provided is divided by 2 and then the grid is guaranteed to never exceed the range of (-maxWidth / 2) - (maxWidth / 2). maxWidth takes precedence over minWidth.
minHeight?: number
The minimum height for the grid. The value you provided is divided by 2 and then the grid is guaranteed to always at least span the range of (-minHeight / 2) - (minHeight / 2).
minWidth?: number
The minimum width for the grid. The value you provided is divided by 2 and then the grid is guaranteed to always at least span the range of (-minWidth / 2) - (minWidth / 2).
onBackgroundReady?: OnBackgroundReadyCallback
Optional function to call when the image has loaded (or otherwise claims to be ready)
showBorder?: boolean
Whether or not to show a thick border around the entire background. Defaults to false.
showTickMarks?: boolean
If true (which is the default), the grid will also draw tick marks between the grid lines.
tickDotRadius?: number
The radius for dots representing grid tick marks (when gridType id GridTypes.dotted). Defaults to 1.
tickMarksPerCell?: number
Number of tick marks to draw per cell. Defaults to 2.
type: string
Type of background to render.
visible?: boolean
Whether or not the background is initially visible. Defaults to true.