Ingesting a Community instance
This is a useful upgrade path for people who have an existing jsPlumb Community edition setup and wish to progressively make use of all the features the Toolkit has to offer. With this method you can instantly add pan/zoom capabilities to your UI, without making any changes to your current code.
It's straightforward to ingest an instance of the Community edition - you use the ingest
function offered by the @jsplumbtoolkit/browser-ui-vanilla-2
package, whose method signature is:
Home > @jsplumbtoolkit/browser-ui-vanilla-2 > ingest
ingest() function
Ingests an existing jsPlumb instance into a new Toolkit instance, and turns the instance's Container into a Surface. Every element that is the source or target of a Connection is added to the Toolkit instance as a Node, and every Connection is added as an Edge. You can provide your own functions for determining the id
and type
of Nodes and Edges, if you need to. This method will throw an error if your jsPlumb instance does not have a Container set; it is a requirement for the Surface widget.
When you ingest an existing jsPlumb instance, its Container
is configured to be a Surface
widget, which makes it pannable and zoomable, and the set of Nodes and Edges it is managing are loaded into the Toolkit's data model.
Signature:
export declare function ingest(params: IngestOptions): Ingester;
Parameters
Parameter | Type | Description |
---|---|---|
params | IngestOptions | Method parameters. |
Returns:
Ingester
Surface A Surface instance whose underlying Toolkit has been loaded with the contents of the jsPlumb instance (you can access the Toolkit itself via surface.getToolkit()
), or, if render
was set to false, a jsPlumbToolkitInstance
..
import { ingest } from "@jsplumbtoolkit/browser-ui-vanilla2"
const ingester = ingest({
jsPlumb:someCommunityInstance
})
Here, instance
is some instance of jsPlumb Community edition. What you get back is an Ingester
, which itself contains a surface
member, and that surface is what you'd normally get back from a call to the Toolkit's render
method.
The IngestOptions
interface is as follows:
Home > @jsplumbtoolkit/browser-ui > IngestOptions
IngestOptions interface
Options for the ingest method
Signature:
export interface IngestOptions
Properties
Property | Modifiers | Type | Description |
---|---|---|---|
edgeIdFunction? | Function | (Optional) Optional function to use to extract the ID from the backing data for some edge | |
edgeTypeFunction? | Function | (Optional) Optional function to use to extract the type from the backing data for some edge | |
idFunction? | Function | (Optional) Optional function to use to extract the ID from some dom element | |
jsPlumb | BrowserJsPlumbInstance | The Community edition instance to ingest | |
nodeSelector? | string | (Optional) optional CSS3 selector that identifies elements in the Community edition that we want to treat as nodes. | |
render? | boolean | (Optional) Defaults to true, meaning a Surface is created. If you set this to false no Surface is created. Unless you can think of a reason why you would not want the Surface to be created it is best to not provide a value for this parameter. | |
renderParams? | SurfaceOptions | (Optional) Optional params for the Surface that is created | |
typeFunction? | Function | (Optional) Optional function to use to extract the type from some dom element |
Supplying Rendering Parameters
You can supply parameters for the Surface widget if you wish to:
const ingester = ingest({
jsPlumb:instance,
renderParams:{
consumeRightClick:false,
clampZoom:false
}
});
Here we've instructed the Toolkit to enable right-click on the Surface (very useful when developing), and also to not clamp the movement of the UI when the user zooms. The default behaviour is to clamp the UI to prevent the content from disappearing if the user zooms in such a way that it ordinarily would.
Adding Nodes after Ingest
Once you've ingested your existing jsPlumb instance you have two options for adding new nodes:
Use your existing mechanism and advise the Surface via its ingest
method.
This method is added to any Surface that was created via the ingest
method; it is not present on a Surface created via the Toolkit's render
method. An example:
const ingester = ingest({ jsPlumb:instance })
const renderer = ingester.surface
// time passes. eventually a DOM element - `el` - has been added to your UI. Now you want to tell the Toolkit about it.
renderer.ingest(el);
ingest
takes an optional second argument providing backing data for the node you are importing:
const ingester = ingest({ jsPlumb:instance })
const renderer = ingester.surface
// time passes. eventually a DOM element - `el` - has been added to your UI. Now you want to tell the Toolkit about it.
renderer.ingest(el, {left:50, top:150, label:"a new node"});
In this example, we provide a label
, as well as a left
/top
position for the node. See below for a discussion of how nodes are positioned.
Use the Toolkit's data binding mechanism to add and render new nodes.
To do this you will most likely want to supply a view in your renderParams
. This defines a variety of things pertaining to the appearance and behaviour of the UI; the link provided goes through your options here in detail. A simple example:
const renderer = ingest({
jsPlumb:instance,
renderParams:{
view:{
nodes:{
"default":{
template:"tmplNode",
events:{
click:(params) => { alert("you clicked node " + params.node.id); }
}
},
events:{
"canvasClick":() => { alert("you clicked on the canvas"); }
}
}
}
});
The point here is that renderParams
supports the exact set of parameters as the params
object on a render
method call on an instance of the Toolkit. In this example we've provided the ID of the template to use to render nodes, and we've registered a click listener for nodes as well as for the whitespace in the work area.
Node Positioning
By default, the Surface resulting from an ingest
call will have a layout of type Absolute
assigned. The initial positions for existing elements will have been retrieved by getting the offset for each of these elements, and these values will be stored in the left
and top
members of each node's backing data.
When you subsequently add a new node, the node will again be placed in the layout at the position derived from its current offset. You can override that behaviour, should you wish to (as shown in the example above), by providing left
and top
values for the node when you ingest it:
renderer.ingest(el, {left:50, top:150, label:"a new node"});