Labeling

With yFiles for HTML 3.0, the labeling API for graph layouts has received a major overhaul. Labels are now fully-fledged elements of the layout graph. They have defined bounds, indices, customizable tags and a reference to their owner, while configuring how labels are handled by the layout algorithms has been streamlined.

Configuration of Layouts

Going forward, all layout algorithms offer a nodeLabelPlacement and edgeLabelPlacement property to specify how the algorithm should handle node labels and edge labels. This replaces properties like considerNodeLabels, considerEdgeLabels, integratedNodeLabeling, integratedEdgeLabeling, and nodeLabelingPolicy by offering all supported policies out of the following:

The two properties can also be used to conveniently add a GenericLabeling step as a post-processing for all node labels, edge labels or both.

const organicLayout = new OrganicLayout({
  // node labels are considered, i.e., overlaps with them avoided
  nodeLabelPlacement: 'consider',
  // edge labels will be placed by generic labeling algorithm
  edgeLabelPlacement: 'generic'
})

// configure the GenericLabeling step
const genericLabeling = organicLayout.genericLabeling
genericLabeling.reduceLabelOverlaps = false

The PreferredPlacementDescriptor class has been renamed to EdgeLabelPreferredPlacement. Preferred placements can be specified for each edge label using the corresponding property on the layout data classes of algorithms that support edge label placement, such as the HierarchicalLayoutData’s edgeLabelPreferredPlacements.

const layout = new HierarchicalLayout()
const layoutData = layout.createLayoutData(graph) // works for both IGraph and LayoutGraph
layoutData.edgeLabelPreferredPlacements.constant =
  new EdgeLabelPreferredPlacement({
    placementAlongEdge: 'at-center'
  })

Generic Labeling Algorithm

Along with the updated labeling API, the generic labeling algorithm has been improved with respect to:

• specifying valid candidate positions for labels
• selecting labels that should be handled by the algorithm
• prioritizing desirable qualities of the resulting labeling

These improvements are described in detail in Generic Labeling.

Labels in Custom Layouts

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

The previous representation of labels as INodeLabelLayouts and IEdgeLabelLayouts has been replaced by the new LayoutNodeLabel and LayoutEdgeLabel types. Additionally, working with labels of the LayoutGraph is now more similar to the workflow in the IGraph.

Labels can be added and removed directly on the graph for any of its nodes and edges, using methods like addLabel or remove. This replaces the functionality of the ILabelLayoutFactory, which was removed as a result.

Nodes and edges now offer a live view of their labels through their labels properties. This replaces the getLabelLayout method on the layout graph, which used to create a list of the labels associated with the graph element at the time it was called.

Labels of the layout graph no longer have any models or model parameters. Layout algorithms (other than GenericLabeling) do not support placing labels on a subset of valid positions during the layout calculation. Despite the removal of label models, the labels are still repositioned with their owner if the owner is moved.