Skip to main content

Plugins

The Surface widget has a plugin architecture, which was new in 5.x. 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 - have all been moved to 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.

Name: miniview

Home > @jsplumbtoolkit/browser-ui > MiniviewPluginOptions

MiniviewPluginOptions interface​

Signature:

export interface MiniviewPluginOptions extends SurfacePluginOptions

Extends: SurfacePluginOptions

Properties​

PropertyModifiersTypeDescription
collapsible?boolean(Optional)
containerElement
elementFilter?(v: Vertex) => boolean(Optional)
enableWheelZoom?boolean(Optional)
suspended?boolean(Optional)
typeFunction?(v: Node | Group) => string(Optional)
visible?boolean(Optional)
wheelReverse?boolean(Optional)
wheelSensitivity?number(Optional)

Lasso​

Provides the Lasso tool.

Name: lasso

Home > @jsplumbtoolkit/browser-ui > LassoPluginOptions

LassoPluginOptions interface​

Signature:

export interface LassoPluginOptions extends SurfacePluginOptions

Extends: SurfacePluginOptions

Properties​

PropertyModifiersTypeDescription
filter?string(Optional) Optional CSS3 filter identifying elements you do not want to lasso.
includeEdges?boolean(Optional) Defaults to false. If true, edges are included in the lasso selection.
invert?boolean(Optional) 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) Optional function to call when lasso selection ends.
onSelect?Function(Optional) Optional function to call when one or more objects has been selected by the lasso.
onStart?Function(Optional) Optional function to call when lasso selection starts.
selectionFilter?(o: Edge | Vertex) => boolean(Optional) 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

Home > @jsplumbtoolkit/browser-ui > PanButtonsPluginOptions

PanButtonsPluginOptions interface​

Signature:

export interface PanButtonsPluginOptions extends SurfacePluginOptions

Extends: SurfacePluginOptions

Properties​

PropertyModifiersTypeDescription
panDistancenumberAmount in pixels to pan the surface by when one of the buttons is pressed and released. Defaults to 50.
panRepeatDistance?number(Optional) Amount in pixels to adjust pan by each time the timer fires. Defaults to 10.
panRepeatInterval?number(Optional) Time in milliseconds between successive adjustment to the pan. Defaults to 60.
startPanTimeout?number(Optional) 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.

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.

Name: drawingTools

Home > @jsplumbtoolkit/browser-ui > DrawingToolsPluginOptions

DrawingToolsPluginOptions interface​

Signature:

export interface DrawingToolsPluginOptions extends SurfacePluginOptions

Extends: SurfacePluginOptions

Properties​

PropertyModifiersTypeDescription
heightAttribute?string(Optional)
ignoreGrid?boolean(Optional)
leftAttribute?string(Optional)
minimumHeight?number(Optional)
minimumWidth?number(Optional)
onDemand?boolean(Optional)
onEdit?() => any(Optional)
topAttribute?string(Optional)
widthAttribute?string(Optional)

Usage​

This plugin can be used without

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

Home > @jsplumbtoolkit/browser-ui > UiStatesPluginOptions

UiStatesPluginOptions interface​

Signature:

export interface UiStatesPluginOptions extends SurfacePluginOptions

Extends: SurfacePluginOptions

Drag Groups​

Provides the ability to manage logical drag groups.

Name: dragGroups

Home > @jsplumbtoolkit/browser-ui > DragGroupsPluginOptions

DragGroupsPluginOptions interface​

Signature:

export interface DragGroupsPluginOptions extends SurfacePluginOptions

Extends: SurfacePluginOptions

Properties​

PropertyModifiersTypeDescription
assignDragGroup(v: Vertex) => DragGroupSpec

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:

Home > @jsplumbtoolkit/browser-ui > GeneratedGridBackgroundOptions

GeneratedGridBackgroundOptions interface​

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

Signature:

export interface GeneratedGridBackgroundOptions extends BackgroundOptions

Extends: BackgroundOptions

Properties​

PropertyModifiersTypeDescription
autoShrink?boolean(Optional) 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(Optional) The radius for dots representing grid positions (when gridType id GridTypes.dotted). Defaults to 2.
grid?Grid(Optional) 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?GridType(Optional) Type of grid - lines or dots. Defaults to lines.
maxHeight?number(Optional) 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(Optional) 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(Optional) 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(Optional) 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).
showBorder?boolean(Optional) Whether or not to show a thick border around the entire background. Defaults to false.
showTickMarks?boolean(Optional) If true (which is the default), the grid will also draw tick marks between the grid lines.
tickDotRadius?number(Optional) The radius for dots representing grid tick marks (when gridType id GridTypes.dotted). Defaults to 1.
tickMarksPerCell?number(Optional) Number of tick marks to draw per cell. Defaults to 2.
visible?boolean(Optional) Whether or not the background is initially visible. Defaults to true.