Paths
A Path represents the path from one vertex (a node/port/group) through a series of edges and intermediate vertices to another vertex. The jsPlumb Toolkit provides several methods for the creation and manipulation of paths.
Path Types
You can work with paths through both an instance of the jsPlumb Toolkit and any Surfaces. The object representing a path differs slightly between the two, in that paths created from a Surface support a few extra (UI-related) methods, such as setVisible.
Getting a Path
To get a Path, you call getPath on either a Toolkit instance or a Surface, with a valid path spec. A quick example to kick off:
toolkit.getPath({
source:someNode,
target:someOtherNode
});
This will return you the shortest path from someNode to someOtherNode, where the Path length is related to its cost.
Paths including ports
By default, the Toolkit will search for paths in "strict" mode, meaning if you supply a Node/Group as source/target, then only Edges directly connected to that Node/Group will be traversed in the search for a Path. Switching off "strict" more relaxes this restriction, and also includes Edges connected to any Ports on the given Node/Group. See below.
Path specs
This is the full list of supported parameters to the getPath method.
Home > @jsplumbtoolkit/browser-ui > PathOptions
PathOptions interface
Path specification.
Signature:
export interface PathOptions
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| edgeFilter? | (n: Edge) => boolean | (Optional) This function is given each Edge's backing data and asked to return true or false - true means include the Edge, false means exclude it. | |
| nodeFilter? | (n: Node) => boolean | (Optional) This function is given each Node/Group's backing data and asked to return true or false - true means include the Node/Group, false means exclude it. | |
| source | string | Vertex | Path source. Either a vertex (node/group/port) or a vertex id. | |
| strict? | boolean | (Optional) Sets whether or not paths are searched strictly by the given source/target. If you supply a node as the source, but there are only edges connected to ports on that node, by default these edges will be ignored. Switching strict to false will mean these edges are considered. | |
| target | string | Vertex | Path target. Either a vertex (node/group/port) or a vertex id. |
Filtering nodes
toolkit.getPath({
source:someNode,
target:someOtherNode,
nodeFilter:function(n) {
return n.data.type != "aTypeIWantToIgnore";
}
});
Here we pass in a function that will be called for every prospective Node in the Path. If it returns false then the Graph treats the Node as if it were at a distance of Infinity - not reachable.
Filtering edges
You can also provide an edgeFilter to control which Edges your Path will traverse:
toolkit.getPath({
source:someNode,
target:someOtherNode,
edgeFilter:function(e) {
return e.data.type != "aTypeIWantToIgnore";
}
});
Note the arguments to these functions are Node or Edge objects from the Toolkit. You may wish to use information contained in those classes to make your decisions, but if you just want to access the original data, you use the data member as shown above.
The Path Object
The basic Path object, as used by an instance of the Toolkit, has this definition:
Home > @jsplumbtoolkit/browser-ui > Path
Path class
Models the path between two Nodes/Ports, which consists of a series of [Group/Node/Port, Edge] pairs.
Signature:
export declare class Path implements FilterableDataset
Implements: FilterableDataset
Constructors
| Constructor | Modifiers | Description |
|---|---|---|
| (constructor)(toolkit, params) | Constructs a new instance of the Path class |
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| result | ShortestPathResult | ||
| toolkit | JsPlumbToolkit |
Methods
| Method | Modifiers | Description |
|---|---|---|
| contains(obj, doNotFuzzyMatchNodes) | Returns true if the path contains the given object (a node, group, port or edge), false otherwise. | |
| deleteAll() | Removes all vertices and edges in this path from the underlying Toolkit. This is an alias for deleteVertices, since deleting a vertex causes its edges to also be deleted. | |
| deleteEdges() | Remove all of the edges in this path from the underlying Toolkit instance. | |
| deleteVertices() | Deletes all the nodes/groups in the path. As with the contains method, there is a special consideration here: if a path passes through ports on a node/group, then that node/group will be, for the purposes of this method, considered to be part of the path and it will be deleted. If you instead wish to delete only the ports in a path, use deletePorts. Note that this method will, of course, have the effect of also deleting all the edges, since the nodes/groups for those edges will no longer exist. | |
| each(fn) | Iterates through the path one step at a time. Each step consists of an object containing a vertex, and, for all entries except the first, an edge member, which supplies the Edge that links to the Vertex (which is why it is null for the first entry). | |
| eachEdge(fn) | Iterates through the Edges in the path one step at a time. There is always one fewer Edges than Nodes/Ports. | |
| eachGroup(fn) | Iterates through the Groups in the path one step at a time. | |
| eachNode(fn) | Iterates through the Nodes in the path one step at a time. | |
| eachVertex(fn) | Iterates through the Nodes/Groups/Ports in the path one step at a time. | |
| exists() | Returns whether or not a given path exists. | |
| filter(spec, includePartials) | ||
| getAllEdgesFor(v) | Gets all the edges in the path that are connected to the given vertex. | |
| getCost() | Gets the cost of the given path. Edges in the Toolkit can have a cost associated with them (the default is 1), and so the cost of any given path is the sum of the cost of all of the edges in the path. | |
| getEdgeAt(idx) | Gets the Edge at the given index in the Path. | |
| getEdgeCount() | Counts the number of edges in the path. This may be zero, if the given path spec did not select a valid path in the Toolkit instance. | |
| getNodeAt(idx) | Gets the Vertex at the given index in the path. | |
| getVertex(obj) | Retrieve the specified vertex from the path | |
| getVertexCount() | Counts the number of vertices in the Path (including the start and end nodes/groups). Note that for the purposes of this calculation, a Port is considered a vertex, as is a Group. | |
| getVertices() | Get all the vertices in the path. | |
| isEmpty() | Returns whether or not a given path is empty |
Note Once you have executed one of the delete*** methods on a path, your path may contain references to objects that no longer exist in the Toolkit.
The Surface's Path Object
Calling getPath(...) on a Surface returns you a UIPath object, which contains a Path and offers a few extra methods for manipulating the appearance of the components of the path. All of the class manipulation methods take a space-delimited string as argument.
Home > @jsplumbtoolkit/browser-ui > UIPath
UIPath class
A wrapper around the Toolkit's path object, which offers a few DOM specific methods.
Signature:
export declare class UIPath
Constructors
| Constructor | Modifiers | Description |
|---|---|---|
| (constructor)(path, surface) | Constructs a new instance of the UIPath class |
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| path | Path |
Methods
| Method | Modifiers | Description |
|---|---|---|
| addClass(clazz) | Adds a CSS class to the elements representing the vertices and edges in the path | |
| addEdgeClass(clazz) | Adds a CSS class to the elements representing the edges in the path | |
| addVertexClass(clazz) | Adds a CSS class to the elements representing the vertices in the path | |
| getEdgeCount() | Gets the total number of edges in the path. | |
| getVertexCount() | Gets the count of vertices in the path. | |
| removeClass(clazz) | Removes a CSS class from the elements representing the vertices and edges in the path | |
| removeEdgeClass(clazz) | Removes a CSS class from the elements representing the edges in the path | |
| removeVertexClass(clazz) | Removes a CSS class from the elements representing the vertices in the path | |
| setVisible(val) | Sets the visible state of all vertices and edges in the path |
Note calling any of the methods from the basic Path object on the result of a getPath call to a Surface that result in a change to the data model will cause those data model changes to be communicated automatically to any other Surface registered on the given Toolkit instance.
Traversing paths in the UI
The Surface widget offers the means to trace paths in the UI - see this page for information.