Skip to main content

Migration from 2.x to 5.x - Rendering

The render call​

When using vanilla Toolkit (ie. no library integration) you will at some point have called render on a Toolkit instance to setup a Surface:

var tk = jsPlumbToolkit.newInstance();
var surface = tk.render({
    container:someElement,
    etc
})

In version 5.x, container is now passed as the first argument to render:

const tk = jsPlumbToolkitBrowserUIVanilla.newInstance()
const surface = tk.render(someElement, {
    etc
})

Connector, Anchor, Endpoint and Overlay Specs​

The syntax of connector, anchor, endpoint and overlay specifications has changed in 5.x. Consider this view from 2.x:

view:{
    edges:{
        default:{
            connector:[ "Bezier", { curviness:50 }],
            endpoint:[ "Dot", { radius:10 }],
            anchor:[ "Continuous", { faces:["top", "bottom"] }],
            overlays:[
                [ "Label", { label:"Foo" }]
            ]
        }
    }
}

In 5.x you would write the same thing as follows:

view:{
    edges:{
        default:{
            connector:{ type:"Bezier", options:{ curviness:50 } },
            endpoint:{ type:"Dot", options:{ radius:10 } },
            anchor:{ type:"Continuous", options:{ faces:["top", "bottom"] }},
            overlays:[
                { type:"Label", options:{ label:"Foo" }}
            ]
        }
    }
}

So the general format for any of these specifications is:

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

View Options​

The specific interface for a view now is SurfaceViewOptions from @jsplumbtoolkit/browser-ui. Here is its definition, and that of some related interfaces:

Source and Target elements​

One of the key pieces of functionality in version 2.x of the Toolkit is the ability to configure connectivity via jtk-source and jtk-target elements in your templates. For example, this is the template for the Action node type in the Flowchart Builder demonstration:

<div style="left:${left}px;top:${top}px;width:${w}px;height:${h}px;" class="flowchart-object flowchart-action">
    <div style="position:relative">
        <svg:svg width="${w}" height="${h}">
            <svg:rect x="10" y="10" width="${w-20}" height="${h-20}"/>
            <svg:text text-anchor="middle" x="${w/2}" y="${h/2}" dominant-baseline="central">${text}</svg:text>
        </svg:svg>
    </div>
    <div class="node-edit node-action"/>
    <div class="node-delete node-action delete"/>
    <div class="drag-start connect"></div>
    <jtk-target port-type="target"/>
    <jtk-source port-type="source" filter=".connect"/>
</div>

Here, we configure connectivity with two elements:

  • <jtk-target port-type="target"/> Instructs the toolkit that this DOM element is an edge target, and that when an edge is connected to this element the Toolkit should use a port type of target. The type of port has a bearing, through your view, on the appearance and behaviour of its endpoint.

  • <jtk-source port-type="source" filter=".connect"/> Instructs the toolkit that this DOM element is an edge source, and that, via the filter attribute, edges can only be dragged from the element with class connect.

In version 5.x, the jtk-source and jtk-target elements do not exist, and this template is as follows:

<div style="left:${left}px;top:${top}px;width:${w}px;height:${h}px;" class="flowchart-object flowchart-action" data-jtk-target="true" data-jtk-port-type="target">
    <div style="position:relative">
        <svg:svg width="${w}" height="${h}">
            <svg:rect x="10" y="10" width="${w-20}" height="${h-20}"/>
            <svg:text text-anchor="middle" x="${w/2}" y="${h/2}" dominant-baseline="central">${text}</svg:text>
        </svg:svg>
    </div>
    <div class="node-edit node-action"/>
    <div class="node-delete node-action delete"/>
    <div class="drag-start connect" data-jtk-source="true" data-jtk-port-type="source"></div>
</div>

The key differences to note are:

  • instead of a <jtk-target..> element, we've marked up the root element with two attributes:

    • data-jtk-target="true" Indicates that the element on which the attribute is set is an edge target
    • data-jtk-port-type="target" Provides the port type to use when an edge is connected to this element as a target

  • instead of a <jtk-source..> element, we've marked up the specific part of the template that we want to use as an edge source with two attributes:

    • data-jtk-source="true" Indicates that the element on which the attribute is set is an edge source
    • data-jtk-port-type="source" Provides the port type to use when an edge is dragged from this element

This arrangement brings a number of benefits over how connectivity in 2.x works:

  • you can have multiple places on a specific vertex element that act as edge sources/targets, and each of those can mandate a different set of port parameters
  • the Toolkit can use delegated event handlers, which reduces memory consumption
  • the Toolkit automatically adds any element marked as data-jtk-source="true" to the list of elements that act as the drag filter for the given vertex. Previously, setting this up was a manual operation.

For further reading, see this page. There are several more attributes you can use than just the ones shown here - there is no regression in terms of the capabilities of this architecture when compared with the capabilities in 2.x.

TOP

Port elements​

In version 2.x you could use a jtk-port element to instruct the Toolkit to add an Endpoint to the UI:

<div class="foo">
    <h1>${name}</h1>
    <jtk-port port-id="aPort" port-type="aPortType"></jtk-port>
</div>

In 5.x this element has been renamed to jtk-endpoint:

<div class="foo">
    <h1>${name}</h1>
    <jtk-endpoint data-jtk-port="aPort" data-jtk-port-type="aPortType"></jtk-endpoint>
</div>

This was done mainly to reduce confusion, since ports are a data model concept and this element is a UI decision.

Endpoints​

An alternative to using jtk-endpoint elements was added to 5.x - you can specify endpoints inside your view instead. For more information see the relevant section in the UI Connectivity page.

Plugins​

In 2.x a number of utilities such as the miniview, the lasso tool, and the nudge buttons, were shipped as part of the Surface itself. Not every application uses all of these tools, though, so in 5.x we've introduced a plugin architecture for the Surface, and we've extracted these tools, as well as a couple of other things, to plugins. The plugins documentation is a good place to read about these, but for the purposes of migration we provide a brief overview here.

Consider this miniview declaration in 2.x:

var surface = myToolkit.render({
    container:someElement,
    miniview:{
        container:miniviewElement
    }
})

in 5.x you'd achieve the same thing like this:

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

var surface = myToolkit.render(someElement, {
    plugins:[
        {
            type: MiniviewPlugin.type,
            options:{
                container:miniviewElement
            }
        }
    ]
})

Every plugin exposes a static type member. Here's another example, with both a miniview and a lasso, with a lasso filter defined, in 2.x:

var surface = myToolkit.render({
    container:someElement,
    miniview:{
        container:miniviewElement
    },
    lassoFilter:".someClass, .someOtherClass"
})

and in 5.x:


import { MiniviewPlugin } from "@jsplumbtoolkit/browser-ui-plugin-miniview"
import { LassoPlugin } from "@jsplumbtoolkit/browser-ui-plugin-lasso"

var surface = myToolkit.render(someElement, {
    plugins:[
        {
            type: MiniviewPlugin.type,
            options:{
                container:miniviewElement
            }
        },
        {
            type: LassoPlugin.type,
            options:{
                filter:".someClass, .someOtherClass"
            }
        }
    ]
})