Skip to main content

Managing connectivity

Connectivity can be controlled at runtime by interceptors - callbacks that can be used to cancel some proposed activity, and that are bound on an instance of the Toolkit by supplying a specific function in the Toolkit constructor options. The Toolkit currently supports five interceptors.

beforeConnect

A function to run before an edge with the given data can be established between the given source and target. Returning false from this method aborts the connection. Note that this method fires regardless of the source of the new edge, meaning it will be called when loading data programmatically.

Method signature

beforeConnect(source: Vertex, target: Vertex): any

Parameters

  • source The source vertex for the new edge
  • target The target vertex for the new edge

Example

Here, we reject connections from any vertex to itself.

const t = newInstance({
beforeConnect:(source: Vertex, target: Vertex) => {
return (source !== target)
}
})

beforeMoveConnection

A function to run before an edge of the given type is relocated from its current source or target to a new source or target. Returning false from this method will abort the move.

Method signature

beforeMoveConnection(source: Vertex, target: Vertex, edge: Edge): any

Parameters

  • source Candidate source. May be the edge's current source, or may be a new source.
  • target Candidate target. May be the edge's current target, or may be a new target.
  • edge The edge that is being moved.

The parameters source and target reflect the source and target of the edge if the move were to be accepted. So if, for example, your user drags a connection by its target and drops it elsewhere, target will be the drop target, not the edge's current target, but source will be the edge's current source. You can access the current source/target via the source and target properties of edge.

Example

Here, we reject moving any edge that has fixed:true in it backing data:

const t = newInstance({
beforeMoveConnection:(source: Vertex, target: Vertex, edge:Edge) => {
return (edge.data.fixed !== true)
}
})

beforeStartConnect

A function to run before an edge of the given type is dragged from the given source (ie. before the mouse starts moving). This interceptor is slightly different to the others in that it's not just a yes/no question: as with the other interceptors, returning false from this method will reject the action, that is in this case it will not allow a connection drag to begin. But you can also return an object from this method, and when you do that, the connection start is allowed, and the object you returned becomes the payload for the new edge.

Method signature

beforeStartConnect(source: Vertex, type: string): any

Parameters

  • source The vertex that is the source for the new edge
  • type The computed type for this new edge.

Example - reject a connection start

const t = newInstance({
beforeStartConnect:(source: Vertex, type:string) => {
return type !== "not-connectable"
}
})

Example - provide an initial payload

const t = newInstance({
beforeStartConnect:(source: Vertex, type:string) => {
return {
type,
message:`initial payload for vertex ${source.id}`
}
}
})

beforeDetach

A function to run before the given edge is detached from the given source vertex. If this method returns false, the detach will be aborted.

Method signature

beforeDetach(source: Vertex, target: Vertex, edge: Edge, isDiscard?: boolean): any

Parameters

  • source The source vertex for the edge that is to be detached.
  • target The candidate target for the edge - may be null, if the edge is being discarded
  • edge The edge that is being detached.
  • isDiscard True if the edge is not now connected to a target.

Example

Here, we reject the detach if the target is null, ie. the user is trying to discard the edge, not relocate it.

const t = newInstance({
beforeDetach(source: Vertex, target: Vertex, edge: Edge, isDiscard?: boolean) => {
return target != null
}
})

beforeStartDetach

Method signature

beforeStartDetach(source: Vertex, edge: Edge): any

A function to run before the given edge is detached from the given source vertex. If this method returns false, the detach will be aborted. The difference between this and beforeDetach is that this method is fired as soon as a user tries to detach an edge from an endpoint in the UI, whereas beforeDetach allows a user to detach the edge in the UI.

Parameters

  • source The source vertex for the edge that the user has started to detach
  • edge The edge that the user has started to detach

Example

Here, we reject the detach if the source vertex has doNotDetachEdges:true in its backing data.

const t = newInstance({
beforeDetach(source: Vertex, edge: Edge) => {
return source.data.doNotDetachEdges !== true
}
})

Live Example

Here's a live example. In this example we provide a beforeStartConnect and beforeDetach interceptor to an instance of the Toolkit. The beforeStartConnect interceptor prevents the user from dragging connections from any vertex whose ID is not an even number. The beforeDetach interceptor reattaches detached connections whose source ID is not an event number

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

const toolkit = newInstance({
beforeStartConnect:(source, type) => {
// only allow connections from nodes whose
// ID is an even number
return parseInt(source.id, 10) % 2 === 0
},
beforeDetach:(source, target, edge, isDiscard) => {
// only allow connections to be detached whose
// source ID is an even number
return parseInt(edge.source.id, 10) % 2 === 0
}
})

Interceptors