Paths

A Path represents the path from one Node/Port through a series of edges and intermediate Nodes/Ports to another Node/Port. The jsPlumb Toolkit provides several methods for the creation and manipulation of Paths.

Toolkit Paths vs Renderer 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 setVisible.

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:

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.

Path Specs

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:

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.

You can also provide an edgeFilter if you control what sorts of 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, supports the following methods:

  • 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.

  • getNodeCount()

Counts the number of Nodes in the Path (including the start and end Nodes). Note that for the purposes of this calculation, a Port is considered a Node.

  • 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.

  • contains(Object, doNotFuzzyMatchNodes)

Returns true if the Path contains the given object (a Node, Port or Edge), false otherwise. By default, if you pass a Node in to this method and the Path passes through a Port on that Node, this method returns true. But if you set doNotFuzzyMatchNodes to true, then this method will return true only if the Node itself is on the Path.

  • deleteEdges()

Deletes all the Edges in the Path

  • deleteNodes()

Deletes all the Nodes in the Path. As with the contains method, there is a special consideration here: if a Path passes through Ports on a Node, then that Node 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 for those Edges will no longer exist.

  • deletePorts()

Deletes all Ports in the Path (and any Edges to/from those Ports). This is strict about deleting only Ports: the Nodes on which those Ports exist will not be deleted.

  • deleteAll()

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 Renderer's Path Object

Calling getPath(...) on a Renderer 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 Renderer 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.