A Path represents the path from one node/port/group through a series of edges and intermediate nodes/ports/groups to another node/port/group. 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 Renderers. The object representing a path differs slightly between the two, in that paths created from a Renderer 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 Renderer, 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
The example above shows the required arguments for retrieving a Path. You can, however, supply a filter function for both Nodes and Edges, allowing you specify with more detail what sort of Path you want to traverse. Consider:
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 if you control what sorts of Edges your Path will traverse:
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, supports the following methods:
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.
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.
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.
Returns true if the path contains the given object (a node, group, port or edge), false otherwise. By default, if you pass a node/group in to this method and the path passes through a port on that node/group, this method returns true. But if you set
doNotFuzzyMatchNodes to true, then this method will return true only if the node/group itself is on the path.
Deletes all the edges in the path
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.
Deletes all ports in the path (and any edges to/from those ports). This is strict about deleting only ports: the nodes/groups on which those ports exist will not be deleted.
Deletes everything that constitutes part of the path. This change will be communicated to all renderers registered with the given Toolkit instance.
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 an extension of the basic Path object, with several extra methods:
addNodeClass(clazz)Adds a class to all Nodes in the Path
addEdgeClass(clazz)Adds a class to all Edges in the Path
removeNodeClass(clazz)Removes a class from all Nodes in the Path
removeEdgeClass(clazz)Removes a class from all Edges in the Path
addClass(clazz)Adds a class to all Nodes and Edges in the Path
removeClass(clazz)Removes a class from all Nodes and Edges in the Path
setVisible(boolean)Shows/hides all objects in the Path.
All of the class manipulation methods actually take a space-delimited string as argument.
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 Renderers registered on the given Toolkit instance.