Annotating objects with drag groups
One of the key differentiators between JsPlumb and other libraries in this space is JsPlumb's level of configurability - more often than not you'll find that once you hit a blocker in some other library, JsPlumb will offer you the ability to do what you need.
A great example of this is JsPlumb's concept of a DragGroup. Simply put, this is a group of vertices that should be dragged together - but as we'll see, it's not quite as simple as that, and it can be used to great effect with minimal work required on your part.
Active vs passive members
In this canvas, try dragging the large green box around. You'll see the two red boxes drag along with it. Now try dragging one of the red boxes - nothing else moves. This is because all of the nodes are inside a drag group, but the large green node is marked active and the red nodes are marked passive:
To achieve this, we used the DragGroupsPlugin, which offers us a declarative means of assigning vertices to drag groups as they are rendered:
import { newInstance,
DragGroupsPlugin } from "@jsplumbtoolkit/browser-ui"
const toolkit = newInstance()
const surface = toolkit.render(someElement, {
"plugins": [
{
"type": DragGroupsPlugin.type,
"options": {
"assignDragGroup": (v) => {
return { id:'dragGroup', active:v.type === 'main' }
}
}
}
]
});
Our dataset looks like this:
{
nodes:[
{id:"1", left:50, top:50, type:"main" },
{id:"2", left:250, top:160 },
{id:"3", left:350, top:100 }
]
}
The key is the assignDragGroup function that we provide. In the implementation above we do two things:
- all vertices are assigned to a drag group called
"dragGroup" - The vertex whose
typeis"main"is markedactive:true; the others are markedactive:false
Multiple drag groups
Our example above used a single drag group, but just in case you're wondering, you can have as many of these as you want. For instance, here's a canvas in which all the red elements are dragged in a single group, and all the green elements are dragged in a different group:
This was an even simpler setup - we just use each node's type to specify its drag group:
import { newInstance,
DragGroupsPlugin } from "@jsplumbtoolkit/browser-ui"
const toolkit = newInstance()
const surface = toolkit.render(someElement, {
"plugins": [
{
"type": DragGroupsPlugin.type,
"options": {
"assignDragGroup": (v) => {
return v.type
}
}
}
]
});
Every element in this example is marked active because that's the default if you do not specify it. All we had to do in this example is return the name of a drag group and JsPlumb adds the vertex as an active participant to that group.
Our dataset in this example is:
{
nodes:[
{id:"1", left:50, top:50, type:"green" },
{id:"2", left:150, top:160, type:"red" },
{id:"3", left:200, top:30, type:"red" },
{id:"4", left:250, top:100, type:"green" }
]
}
Annotating Objects
To get back to the point of this post: how can we use this functionality to annotate objects? A key requirement when implementing the ability to annotate objects in a diagram is that the user wants to be able to place the annotation wherever they like around the object that is being annotated, depending on what else is in the diagram. So the annotation needs to be draggable, but if the user moves the annotated object, the annotation should stay close - and that's why we think the drag groups plugin is perfect for the job.
Consider this dataset:
{
nodes:[
{ id:"1", type:"main", left:50, top:50 },
{ id:"2", type:"main", left:300, top:50 },
{ id:"3", type:"annotation", text:"I belong to node 1", ref:"1", left:70, top:-40 },
{ id:"4", type:"annotation", text:"I belong to node 1", ref:"1", left:-90, top:120 },
{ id:"5", type:"annotation", text:"I belong to node 2", ref:"2", left:380, top:160 }
]
}
We've got two nodes of type main, and three nodes of type annotation, each of which have a ref member, which points to a main node. We want to be able to drag our main nodes around and have the annotation nodes follow, but we also want to be able to position the annotation nodes around the main nodes where we please. This is easily achieved:
import { newInstance,
DragGroupsPlugin } from "@jsplumbtoolkit/browser-ui"
const toolkit = newInstance()
const surface = toolkit.render(someElement, {
"plugins": [
{
"type": DragGroupsPlugin.type,
"options": {
"assignDragGroup": (v) => {
return v.type === 'main' ? v.id : {id:v.data.ref, active:false}
}
}
}
]
});
- For nodes of type
main, we just return the node's id:v.id - For nodes of type
annotation, we return therefas the drag group id, and mark the vertex passive:{id:v.data.ref, active:false}.
Which gives us this arrangement. Dragging a green node will drag its related annotations along with it, but annotations can be dragged separately, to position them in relation to their reference element:
And there you have it! Annotated objects using just a few lines of configuration.
Housekeeping
One thing to keep in mind is that the annotations and the edges that connect them to their reference nodes will not automatically be removed by JsPlumb if the reference node is removed from the dataset. Don't worry, though - we've got you. We'll use another of JsPlumb's capabilities you won't find in other libraries in this space - Transactions - to cleanup the annotations, but in an undo/redo friendly way.
Try clicking one of the ✖ buttons below. We'll remove the node the button belongs to, and we'll also remove any annotations that are attached to it (code follows below) :
To remove a node and its annotations in an undo-friendly way, we find everything we want to delete and then perform all the removals inside a transaction. An example function, into which you'd pass the JsPlumb instance and the ID of the node to cleanup, is:
function removeNode(toolkit, nodeId) {
const annotations = toolkit.getNodes().filter(n => n.data.ref === nodeId)
toolkit.transaction(() => {
annotations.forEach(a => toolkit.removeNode(a))
toolkit.removeNode(nodeId)
})
}
How you wire up this function will depend on what library integration you are using.
import { newInstance, EVENT_TAP } from "@jsplumbtoolkit/browser-ui"
const toolkit = newInstance()
toolkit.render(someElement, {
...,
modelEvents:[
{
selector:"[data-jtk-delete='true']",
event:EVENT_TAP,
callback:(event, element, info) => {
const annotations = toolkit.getNodes().filter(n => n.data.ref === info.obj.id)
toolkit.transaction(() => {
annotations.forEach(a => toolkit.removeNode(a))
toolkit.removeNode(info.obj.id)
})
}
}
]
})
Further reading
-
Read about the drag groups plugin here: https://docs.jsplumbtoolkit.com/toolkit/7.x/lib/plugins/drag-groups
-
Read about JsPlumb's support for batching operations in transactions here: https://docs.jsplumbtoolkit.com/toolkit/7.x/lib/undo-redo#transactions
Start a free trial
Get in touch!
If you'd like to discuss any of the ideas/concepts in this article we'd love to hear from you - drop us a line at hello@jsplumbtoolkit.com.