Hierarchical Layout

This section describes the major changes to the HierarchicalLayout (formerly HierarchicLayout).

As with all major layout algorithms, the HierarchicalLayout no longer inherits from MultiStageLayout, but directly implements ILayoutAlgorithm. The layout stages are now managed by a LayoutStageStack, which can be obtained via the layoutStages property; see the migration chapter Layout Stages and Multi-Stage Layouts for more details.

Renamed, Moved, and Removed Classes and Members

The following table lists the renamed, moved, and removed classes and members of the major classes of HierarchicalLayout. In addition to the changes listed here, the expert API was streamlined as well; see Major Changes to Expert API.

Changed Default Values and Behavior Changes

The default routing style of the HierarchicalLayout has changed from POLYLINE to ORTHOGONAL. The routing style can be specified via the routingStyleDescriptor property on HierarchicalLayoutEdgeDescriptor. In case that one HierarchicalLayoutEdgeDescriptor suffices for all edges, it can be set via the defaultEdgeDescriptor property on HierarchicalLayout.

Node labels are now considered by default. To change this behavior, set the nodeLabelPlacement property to the desired value. It is now also easier to place node labels with GenericLabeling by setting the value to GENERIC.

Edge labels are now placed by an integrated labeling algorithm by default. To change this behavior, set the edgeLabelPlacement property to the desired value. It is now also easier to place edge labels with GenericLabeling by setting the value to GENERIC.

By default, the HierarchicalLayout now prefers more symmetric layouts at the expense of other layout qualities such as compactness. The influence of symmetry on the layout can be configured via the CoordinateAssigner.symmetryOptimizationStrategy property. The CoordinateAssigner that is used by the HierarchicalLayout is available via the HierarchicalLayout.coordinateAssigner property.

The gridSpacing property of HierarchicalLayout now requires the argument to be non-negative. To specify that no grid should be used, set the value to 0.

Incremental Hints

Specifying incremental hints has been simplified. In the simple case where some nodes or edges should be marked as incremental for all parts of the layout algorithm, the incrementalNodes and incrementalEdges properties on the HierarchicalLayoutData can be used.

// create a HierarchicalLayout which rearranges only the incremental graph elements
const hl = new HierarchicalLayout({ fromSketchMode: true })

// provide additional data to configure the HierarchicalLayout
const hlData = hl.createLayoutData(graph)
// specify the nodes to rearrange
hlData.incrementalNodes.source = incrementalNodes
// specify the edges to rearrange
hlData.incrementalEdges.source = incrementalEdges

graph.applyLayout(hl, hlData)

To specify more specific hints, it is no longer necessary to use an IIncrementalHintsFactory. Instead, the enum values of IncrementalNodeHint and IncrementalEdgeHint can be used directly. The interface IIncrementalHintsFactory has been removed.

// create a HierarchicalLayout which rearranges only the incremental graph elements
const hl = new HierarchicalLayout({ fromSketchMode: true })

// provide additional data to configure the HierarchicalLayout for incremental edges
const hlData = hl.createLayoutData()
// sequence hint for incremental edges
hlData.incrementalEdges.source = incrementalEdges

// provide additional GenericLayoutData to configure incremental nodes
const glData = new GenericLayoutData()
glData.addItemMapping(
  HierarchicalLayout.INCREMENTAL_NODE_HINTS_DATA_KEY
).mapperFunction = (node) => {
  if (incrementalNodes.includes(node)) {
    // create a hint for incremental nodes
    if (graph.isGroupNode(node)) {
      // special hint for groups
      return IncrementalNodeHint.INCREMENTAL_GROUP
    }
    if (fixedNodes.includes(node)) {
      // exact layer for the fixedNodes
      return IncrementalNodeHint.USE_EXACT_COORDINATES
    }
    // simple layer hint for all other nodes
    return IncrementalNodeHint.LAYER_INCREMENTALLY
  }
  return IncrementalNodeHint.NONE
}

// combine both layout data instances
const layoutData = hlData.combineWith(glData)

graph.applyLayout(hl, layoutData)

// create a HierarchicalLayout which rearranges only the incremental graph elements
const hl = new HierarchicalLayout({ fromSketchMode: true })

// provide additional data to configure the HierarchicalLayout for incremental edges
const hlData = hl.createLayoutData()
// sequence hint for incremental edges
hlData.incrementalEdges.source = incrementalEdges

// provide additional GenericLayoutData to configure incremental nodes
const glData = new GenericLayoutData<INode, IEdge, ILabel, ILabel>()
glData.addItemMapping(
  HierarchicalLayout.INCREMENTAL_NODE_HINTS_DATA_KEY
).mapperFunction = (node: INode) => {
  if (incrementalNodes.includes(node)) {
    // create a hint for incremental nodes
    if (graph.isGroupNode(node)) {
      // special hint for groups
      return IncrementalNodeHint.INCREMENTAL_GROUP
    }
    if (fixedNodes.includes(node)) {
      // exact layer for the fixedNodes
      return IncrementalNodeHint.USE_EXACT_COORDINATES
    }
    // simple layer hint for all other nodes
    return IncrementalNodeHint.LAYER_INCREMENTALLY
  }
  return IncrementalNodeHint.NONE
}

// combine both layout data instances
const layoutData = hlData.combineWith(glData)

graph.applyLayout(hl, layoutData)

GridComponents (Formerly Buses)

The bus structure concept of the HierarchicalLayout has been renamed to GridComponent to prevent confusion with the buses (bus-style edge routing) of the EdgeRouter. GridComponents can be configured with GridComponentDescriptor instances, which can be set via the gridComponents property of the HierarchicalLayoutData.

Layer and Sequence Constraints

The changes described in this section only affect users who directly used the LayoutGraph API, for example, when writing custom layout algorithms.

In yFiles for HTML 2.6, defining layer or sequence constraints when working directly on the LayoutGraph factories required using the ILayerConstraintFactory and ISequenceConstraintFactory interfaces. These interfaces have been removed and replaced by the LayoutGraphLayerConstraints and LayoutGraphSequenceConstraints classes.

However, it is now highly recommended that you define layer and sequence constraints using the HierarchicalLayoutData, which is also available for the LayoutGraph.

const layout = new HierarchicalLayout()
// Layout data is now also available for LayoutGraphs
const layoutData = layout.createLayoutData(graph)

// Ensure that node2 is placed after node1
layoutData.sequenceConstraints.placeNodeBeforeNode(node1, node2)
// Also place another node at the very start
layoutData.sequenceConstraints.placeNodeAtHead(firstNodeInLayer)

Major Changes to Expert API

The changes described in this section only affect users who directly worked with the LayoutGraph API, such as when writing custom layout algorithms.

This section aims to provide a broad overview of the changes to the classes that define the low-level details governing the inner workings of the HierarchicalLayout. It is not meant to be a comprehensive list of all changes.

Several interfaces were removed or replaced by their concrete implementations, as shown in the following table.

Several protected methods have also been removed.