Hierarchy Layout
The Hierarchy layout positions vertices in a hierarchy, oriented either vertically or horizontally, following a slightly modified version of the 'Sugiyama' method. This layout is available from version 5.5.0 onwards, offers more flexibility in the data model than the Hierarchical layout, specifically with regards to nodes that have multiple parents, or that have edges to other nodes that are not in the immediate layer above or below.
Over time we expect this layout to supplant the Hierarchical layout, as we add more features.
Don't confuse this layout with the Hierarchical layout, which functions in a similar way but which lacks some of the flexibility that this layout has. The Hierarchy layout is available from the @jsplumbtoolkit/layout-hierarchy package.
const surface = toolkit.render(someElement, {
layout:{
type:"Hierarchy",
options:{
}
}
});
Parameters
Home > @jsplumbtoolkit/layout-hierarchy > HierarchyLayoutParameters
HierarchyLayoutParameters interface
Optional parameters for a Hierarchy layout
Signature:
export interface HierarchyLayoutParameters extends AbsoluteBackedLayoutParameters
Extends: AbsoluteBackedLayoutParameters
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| axis? | HierarchyLayoutAxis | (Optional) Either horizontal (the default, groups of child vertices are laid out in rows) or vertical (groups of child vertices are laid out in columns) | |
| edgeNodeSize? | number | (Optional) Optional size - in the main axis - to use for edge nodes, which are dummy nodes (not visible) that are inserted on a layer to allow an edge to pass through to a layer below. | |
| gatherUnattachedRoots? | boolean | (Optional) If true root nodes that do not have children will be positioned adjacent to the last root node that does have children. When false (which is the default), unattached roots are spaced apart so that they do not overlap any child trees. | |
| invert? | boolean | (Optional) If true, the layout will be inverted in its perpendicular axis. For instance, if axis is "horizontal" and invert is true, the root nodes of the layout will be placed at the bottom of the layout, and their children will be placed above them. | |
| maxIterations? | number | (Optional) Maximum number of iterations to run. Defaults to 24. | |
| maxIterationsWithoutImprovement? | number | (Optional) Number of iterations to try rearranging the graph without an improvement in legibility before accepting the current state. Defaults to 2. | |
| placementStrategy? | PlacementStageStrategy | (Optional) The strategy to use when placing vertices. Default is 'center', meaning every row is centered around the axis orthogonal to the axis in which the vertices are laid out. | |
| respectEdgeDirection? | boolean | (Optional) If true, the layout will take into account 'directed' edges, and attempt to place the source of any given edge in a higher layer than the edge's target. This flag also has the effect of positioning any nodes that act only as the source of one or more edges on the root layer of the layout. It isn't always possible to place the source of some edge in a higher layer than the edge's target, due to the graph's topology, but this flag will ensure the layout makes every effort to do so. | |
| rootNode? | any | (Optional) Optional node to use as the root. If this is not provided the layout calculates the best candidate based upon incoming and outgoing edges for each vertex. |
Home > @jsplumbtoolkit/core > AbsoluteBackedLayoutParameters
AbsoluteBackedLayoutParameters interface
Parameters for a layout that extends AbsoluteBackedLayout
Signature:
export interface AbsoluteBackedLayoutParameters extends LayoutParameters
Extends: LayoutParameters
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| absoluteBacked? | boolean | (Optional) Defaults to false. If true, then the layout will use any position values found in the data for a given vertex. |
Home > @jsplumbtoolkit/core > LayoutParameters
LayoutParameters interface
Base interface for layout parameters. All layout parameter interfaces extend this.
Signature:
export interface LayoutParameters extends Record<string, any>
Extends: Record<string, any>
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| height? | number | (Optional) Optional fixed height for the layout. | |
| locationFunction? | LocationFunction | (Optional) Optional function that, given some vertex, can provide the x/y location of the vertex on the canvas | |
| padding? | PointXY | (Optional) Optional padding to put around the elements. | |
| width? | number | (Optional) Optional fixed width for the layout. |
The layout at the top of this page shows the horizontal. Here we show the same dataset in the vertical orientation:
Placement Strategy
You can use a few different "placement strategies" with the Hierarchy layout. By default, every level in the layout is centered around the middle of the main axis. You can align all the layers to the start or the end of the layout, though, by providing a value for placementStrategy.
Hierarchical layout with placementStrategy:start
Hierarchy layout with placementStrategy:end
A possible future enhancement to the Hierarchy layout that we have in mind is to offer a placement strategy in which children of a given vertex are grouped, wherever possible, underneath their parent.
Determining the root node(s)
In the Hierarchy layout there are always one or more "root" vertices, which are vertices that are to be placed at the root of the hierarchy. The layout calculates these by looking for vertices that are not the target of any edges. If it finds none, an arbitrary vertex will be used as the initial root. From each root, edges are followed and connected vertices are placed, until there are no more edges to follow. There may be more than one root in a given dataset.
You can specify a root node by setting it as the rootNode:
toolkit.render(someElement, {
layout:{
type:"Hierarchy",
options:{
rootNode:rootNode,
axis:"horizontal"
}
}
});
Note that we said "a" root node, and not "the" root node, as after placing every node connected to your nominated root, the layout will continue to place other root nodes that it has found.
Edge routing
As of release 5.5.1 of the Toolkit there is currently no package that supports routing edges around nodes, but such a package is in development, and the Hierarchy layout has been written with a view to supporting it. When, as in the dataset below, an edge traverses more than one level, a dummy node is inserted into each layer that the edge passes through.
It's not immediately apparent where the dummy nodes are inserted. However, you can control their size, via the edgeNodeSize option, so to illustrate the concept, here we set edgeNodeSize to 300 pixels, and it's easier to see that in this particular dataset, a dummy node is inserted at the start of the 3rd and 4th levels in the hierarchy: