Data Model / Paths
☰

Paths

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

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.

By default, the Toolkit will search for paths in "strict" mode, meaning if you supply a Node as source/target, then only Edges directly connected to that Node 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. See below.

This is the full list of supported parameters to the getPath method:

  • source Node|Port|String Source node or port, or id of source node/port
  • target Node|Port|String Target node or port, or id of target node/port
  • strict boolean Sets whether or not paths are searched strictly by the given source/target. If, for instance, 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. This is set to true by default.
  • nodeFilter (Node)=>boolean Optional function that is given each Node in turn and asked to return true or false - true means include the Node, false means exclude it.
  • edgeFilter (Edge)=>boolean Optional function that is given each Edge in turn and asked to return true or false - true means include the Edge, false means exclude it.

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

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

  • deleteEdges()

Deletes all the edges in the path

  • deleteNodes()

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.

  • deletePorts()

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.

  • deleteAll()

Deletes everything that constitutes part of the path. This change will be communicated to all Surface 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.

Calling 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 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 Surface registered on the given Toolkit instance.