Custom Routers

Each Link performs a very fast default computation of its desired path, its "route", based only on the properties of the Link and the properties of the port objects that it is connected with. This is discussed in the pages on Links and Link connection points.

To implement more complex behavior, GoJS provides a way to customize link routing by allowing consideration of other Nodes and Links with the Router class. Routers can be created and added to the Diagram's Diagram.routers list, and these will operate on links during updates.

Routing basics

Routers work by defining a method, Router.routeLinks, which takes a collection of recently recomputed link routes, plus a collection context that is either a Group or the Diagram. This method is called by the Diagram during the update phase after layouts are performed.

During updates to the Diagram, GoJS does a depth-first walk of all Groups in the Diagram, starting with the leaf-most Groups, and performs their layouts if invalid. For each of the routers present in Diagram.routers, the Diagram calls Router.canRoute, passing it the Group. If that predicate returns true, it calls Router.routeLinks. Finally, the Diagram performs the Diagram.layout if it is invalid, and calls Router.canRoute and possibly Router.routeLinks with the Diagram itself.

Group bounds are normally affected by their member links because Group.computesBoundsIncludingLinks is true by default. You can set this property to false if you do not want or need the bounds of member links to affect the bounds of any Groups.

Simple Router example

The sample below shows a simple use case of a Router, which will cause the vertical segments of links in a TreeLayout to be positioned at a fixed distance from the next node in the tree. This custom router is designed to only operate on the whole Diagram, not individual Groups.

Avoids Links Router

When creating diagrams with many Links using Orthogonal or AvoidsNodes routing, it is common to have segments of separate links overlapping. GoJS provides an extension, the AvoidsLinksRouter, which will cause such segments to instead be routed in parallel while minimizing the number of crossings between segments.

For a demonstration of the AvoidsLinksRouter in a diagram with many links, see the Avoids Links Router sample.

Link Label Router

When creating diagrams with many Links that have labels on them, it is common to have those labels sometimes overlapping each other. GoJS provides an extension, the LinkLabelRouter, which will cause such labels to be shifted slightly in order to reduce the overlaps.

Although that Router does not actually modify any Link routes, it may modify the bounds of some Links, and it can only do so after the default routing of all Links has already taken place.

For a demonstration of the LinkLabelRouter in a diagram with many links, see the Link Label Router sample.