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.
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
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:
This will return you the shortest path from
someOtherNode, where the Path length is related to its
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.
This is the full list of supported parameters to the
export interface PathOptions
|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 |
|target||string | Vertex||Path target. Either a vertex (node/group/port) or a vertex id.|
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.
You can also provide an
edgeFilter to control which Edges your Path will traverse:
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:
Models the path between two Nodes/Ports, which consists of a series of [Group/Node/Port, Edge] pairs.
export declare class Path implements FilterableDataset
|(constructor)(toolkit, params)||Constructs a new instance of the |
|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 |
|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 |
|each(fn)||Iterates through the path one step at a time. Each step consists of an object containing a |
|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.|
|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
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.
A wrapper around the Toolkit's path object, which offers a few DOM specific methods.
export declare class UIPath
|(constructor)(path, surface)||Constructs a new instance of the |
|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.