Skip to main content

Path Tracing

The jsPlumb Toolkit supports tracing a path between a given source and target node using an Overlay.

Example


import { newInstance } from "@jsplumbtoolkit/browser-ui-vanilla"

// setup two nodes and connect

let toolkit = newInstance()
let renderer = toolkit.render(someElement)
toolkit.load({
data:{
nodes: [ a bunch of nodes. let's pretend they have IDs from 1 - 34 ],
edges:[ a bunch of edges ]
}
});

let transport = renderer.tracePath({
source:1,
target:23,
overlay:"Arrow"
});

if (!transport.pathExists) {
alert("There was no such path");
}

In this example we've attempted to trace an arrow overlay along the shortest path from node 1 to node 23, using the default animation options, which are:

  • travel at 100 pixels per second
  • use a frame rate of 30 frames per second
  • dwell on each intermediate element for 250 milliseconds

The return values from the tracePath method is a PathTransport object, which offers the following methods:

  • play() Starts the animation
  • pause() Pauses the animation
  • cancel() Cancels the animation
  • bind(event:string, handler:Function) Binds an event handler. Only one event - "state" - is fired, in fact, and it's generally better practise to supply a listener to the tracePath method call instead, because binding to the transport after it has been created means you will miss the initial start state event change.

We can enhance the previous call, then, with an event listener like this:


import { newInstance } from "@jsplumbtoolkit/browser-ui-vanilla"

function stateChange(newState) {
console.log("The new state is " + newState);
}

// setup two nodes and connect
let toolkit = newInstance()
let renderer = toolkit.render(someElement)
toolkit.load({
data:{
nodes: [ a bunch of nodes. let's pretend they have IDs from 1 - 34 ],
edges:[ a bunch of edges ]
}
});

let transport = renderer.tracePath({
source:1,
target:23,
overlay:"Arrow",
listener: stateChange
});

if (!transport.pathExists) {
alert("There was no such path");
}

The Path Tracing demonstration has an example of a full setup with an event listener and play/pause/cancel controls.


Animation Options

You can change the default animation options if you need to:

const transport = renderer.tracePath({
source:1,
target:23,
overlay:"Arrow",
options:{
speed: 25, // pixels per second
rate: 60 // frames per second
dwell: 50 // dwell on intermediate elements for 50 milliseconds
}
});

Tracing a specific Path

The two examples given so far do not mandate any specific path to travel from the source to the target, so the Toolkit will pick the shortest path (which is controlled by both number of hops and edge cost if you have provided that for any of your edges). However, you can supply any path to this method, should you want to.

To get a path that is not the shortest path you will need to make use of a nodeFilter and/or edgeFilter when you call getPath on some Toolkit instance, as discussed on this page. An example:

let path = toolkit.getPath({
source:1,
target:23,
edgeFilter:(edge) => {
return !edge.data.type === "aTypeIWouldIgnore"
}
});

This path can then be passed to tracePath instead of providing a source and target:

renderer.tracePath({
path:path,
overlay:"Arrow",
options:{
speed: 25, // pixels per second
rate: 60, // frames per second
dwell: 50 // dwell on intermediate elements for 50 milliseconds
}
});

CSS Classes

During the lifetime of a path traversal, the following classes are used:

ClassAssigned ToPurpose
jtk-animate-node-traversingNodesIndicates the path is currently dwelling on the given Node
jtk-animate-edge-traversingEdgesIndicates the Edge is currently being traversed

Events

These events will be fired by the renderer during a path traversal:

EventDescriptionParameters
startOverlayAnimationFired at the beginning of the traversal.connection:Connection
endOverlayAnimationFired at the very end of the traversal.connection:Connection
startNodeTraversalFired when a node has been reached and is being traversed.
endNodeTraversalFired at the end of traversing a Node.