Migrating to 3.0 from 2.6

yFiles for HTML 3.0 introduces a comprehensive revision of many parts of the API. Unlike previous major releases, where we prioritized backward compatibility, this version removes technical debt to provide a more intuitive, consistent, and streamlined experience. The result is a more modern and efficient API that simplifies development.

However, this also results in many incompatible changes for existing projects. This chapter describes of the most significant changes in more detail and helps with the migration. For a complete list of changes, refer to the changelog.

Many changes can be found in the layout part of the library. These changes include major renamings, changed default values, and removed API. In addition, there have been major changes to basic layout concepts including, among others, the graph model, the handling of ports, the maximum duration/abort handling, the scope of affected elements, and the handling of grouped graph structures.

This chapter also contains layout-algorithm-centric sections that summarize the main changes to individual algorithms, such as the Hierarchic Layout, Organic Layout, Tree Layout, Orthogonal Layout, Edge Router, and Generic Labeling.

New RenderTree and IObjectRenderer API

The new renderTree property on the CanvasComponent now encapsulates all low-level render object related API. Previously, these APIs were directly available on the CanvasComponent. This affects the following members on CanvasComponent:

In addition, the ICanvasObject interface and related types have been renamed and slightly adjusted. In particular:

Additional Changes

Events and Event Registration

The event registration system for event listeners has been updated to align with the DOM model, transitioning to a standardized approach.

New Event Registration Methods

Method Parameters

Benefits

Migration Example

graph.addNodeCreatedListener(callback)

graph.addEventListener('node-created', callback)

Migration Steps

Callback Signature Changes

graph.addNodeCreatedListener((sender, eventArgs) => {
    // handle node creation
})

graph.addEventListener('node-created', (eventArgs) => {
    // handle node creation
})

Important Notes

Mouse and Touch Events

yFiles for HTML 3.0 introduces a unified input event handling system using PointerEventArgs. This replaces the separate MouseEventArgs and TouchEventArgs classes. This new class handles mouse, touch, and pen inputs, simplifying event handling and reducing code duplication.

PointerEventArgs provides properties to identify the source of the event (mouse, touch, or pen) and access the specific input data for each.

Pointer Type

The PointerEventArgs class provides the pointerType property, which allows you to identify the type of device that triggered the event. The pointerType property is of type PointerType enum, which has the following possible values:

You can use this property to tailor your event handling logic based on the input device. For example:

graphComponent.addEventListener('pointer-move', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.MOUSE) {
    // Handle mouse-specific logic
    console.log('Mouse move event')
  } else if (evt.pointerType === PointerType.TOUCH) {
    // Handle touch-specific logic
    console.log('Touch move event')
  } else if (evt.pointerType === PointerType.PEN) {
    // Handle pen-specific logic
    console.log('Pen move event')
  }
})

The eventType property (of type PointerEventArgs) provides even more specific information about the event:

Direct Property Access

PointerEventArgs provides direct access to properties specific to different input types. This includes:

Enhanced Gesture Handling

The PointerEventArgs simplifies gesture handling by providing a unified event stream for all input types. You can use the pointerType and eventType properties to create flexible gesture recognizers that work with mouse, touch, and pen input.

Mapping Previous API to New

The following table shows how to map properties from the old MouseEventArgs and TouchEventArgs classes to the new PointerEventArgs class:

PointerButtons Enum Mapping

The PointerButtons enum now encompasses states for mouse, pen, and touch inputs. Here’s how the old values map to the new enum:

Example: Migrating a Mouse Move Handler

graphComponent.addMouseMoveListener((sender, evt: MouseEventArgs) => {
  const worldLocation = evt.location
  console.log(`Mouse moved to: ${worldLocation.x}, ${worldLocation.y}`)
})

graphComponent.addEventListener('pointer-move', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.MOUSE) {
    const location = evt.location
    console.log(`Mouse moved to: ${location.x}, ${location.y}`)
  }
})

Example: Migrating a Touch Tap Handler

graphComponent.addTouchTapListener((sender, evt: TouchEventArgs) => {
  const worldLocation = evt.location
  console.log(`Touch tapped at: ${worldLocation.x}, ${worldLocation.y}`)
})

graphComponent.addEventListener('pointer-click', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.TOUCH) {
    const worldLocation = evt.location
    console.log(`Touch tapped at: ${worldLocation.x}, ${worldLocation.y}`)
  }
})

Pressure-sensitive Drawing

You can use the pressure property to change thickness or opacity of the created element based on the pressure applied by a pen:

graphComponent.addEventListener('pointer-drag', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.PEN) {
    const strokeThickness = evt.pressure * 5 // Scale pressure to a thickness value
    // ... use strokeThickness to draw the line ...
  }
})

Enhanced Touch Interactions

The pointerSize property can be used to create more realistic touch interactions. For example, you could adjust the size of an element based on the size of the touch contact area.

graphComponent.addEventListener('pointer-drag', (evt: PointerEventArgs) => {
  if (evt.pointerType === PointerType.TOUCH) {
    const touchWidth = evt.pointerSize.width
    const touchHeight = evt.pointerSize.height
    // ... adjust element size based on touchWidth and touchHeight ...
  }
})

Compatibility Considerations

graphComponent.addMouseDownListener((sender, mouseEventArgs) => {
    // handle mouse down
})

graphComponent.addEventListener('pointer-down', (evt: PointerEventArgs) => {
    // handle node creation
    if (evt.pointerType === PointerType.MOUSE) {

    }
})

User Interaction Changes

The default user interactions have been updated. We have carefully updated keyboard shortcuts and default gestures to align with the standards found in many popular drawing and design applications like PowerPoint and Photoshop. If you have made only few customizations, the changes will be incompatible but likely beneficial.

Depending on your application, you may want or need to migrate your existing behavior to the new release. Reverting the behavior to match the old defaults is possible but requires different steps depending on the type of change.

Reverting Default Gestures in GraphEditorInputMode

The most noticeable change in GraphEditorInputMode is how elements are moved interactively. In version 2.6, you had to explicitly enable the option that allowed users to move elements without selecting them first. This is now the default behavior and can be disabled or controlled using the movableUnselectedItems property.

To continue supporting edge creation, the way edge creations are initiated has changed. Users now hover over a node to display the port candidates. Then, they can start dragging a new edge from a candidate, even if the node is selected. You can revert to the old behavior by setting startOverCandidateOnly to false, disabling moveUnselectedItemsInputMode, and assigning a higher priority to moveSelectedItemsInputMode.

const geim = new GraphEditorInputMode({
  createEdgeInputMode: { priority: 110, startOverCandidateOnly: false,
    showPortCandidates: 'end' },
  moveSelectedItemsInputMode: { priority: 100 },
  moveUnselectedItemsInputMode: { enabled: false }
})

In version 2.6, it was not intuitive for users on touch devices to cancel an edge creation gesture that was started by accident. By default, moving back to the start node without creating enough bends now cancels edge creation instead of creating a self-loop. You can revert to the old behavior by setting minimumSelfLoopBendCount to 0. In version 2.6, this property is set to 2 by default.

Changed Keyboard Shortcuts

Most keyboard shortcuts in yFiles for HTML are configured via the yfiles.resources object, as explained in Customizing String Resources.

With yFiles for HTML 2.6, a number of changes were implemented:

The names of the shortcut modifiers have been adjusted. If you have customized them, replace Ctrl with Control.

To revert to the original shortcut, set the property to the "old value."

yfiles.resources["invariant"]["ExtendSelectionUpKey"] = "Control+ArrowUp"

delete yfiles.resources["invariant"]["IncreaseZoomKey"]

Theming

The Theme class and ThemeVariant enum have been removed. You can now change the theming through CSS classes.

ThemeVariant.CLASSIC has been removed and has no CSS replacement.

Migration Example

graphComponent.theme = new Theme({ scale: 2 })

<div id="graphComponent" style="--yfiles-theme-scale: 2"></div>

graphComponent.style.setProperty('--yfiles-theme-scale', '2')

For more about theming, refer to the Themes section.

Migrating WebGL2 Styles

In this release, WebGL2 styles now implement the standard interfaces:

This integration enables seamless usage with standard IGraph API methods and infrastructure.

The following features now work directly with WebGL styles and no longer require special handling:

const node = graph.createNode({
  style: new WebGLShapeNodeStyle({
    fill: '#242265',
    effect: 'ambient-stroke-color',
    stroke: '3px dashed orangered',
    shape: 'hexagon',
  })
})

graph.nodeDefaults.style = new WebGLImageNodeStyle(someImageData)

graphComponent.inputMode = new GraphEditorInputMode({
  createEdgeInputMode: {
    edgeDefaults: {
      style: new WebGLArcEdgeStyle(
        { stroke: "3px solid darkblue", height: 20, fixedHeight: true }
      )
    }
  }
})

Level of Detail Rendering with WebGL and Non-WebGL styles

For applications that dynamically switch between WebGL mode and SVG/HTML/Canvas rendering, the WebGL styles are automatically mapped to visually similar SVG-based styles. When using level of detail rendering and custom styles are desired in SVG mode, a convenience implementation is available. This implementation implements the corresponding style interface, allowing you to specify both the WebGL and the non-WebGL style instance.

const node = graph.createNode({
  style:
    new WebGLNodeStyleDecorator(
      myCustomNodeStyle,
      new WebGLImageNodeStyle(someImageData)
    )
})

WebGL API Changes in yFiles for HTML 3.0

Most types that had a WebGL2 prefix now have the 2 removed from their name.

Clipboard API

GraphEditorInputMode Event Changes

The following events now use ItemsEventArgs and have their names adjusted. See Events and Event Registration for details on how events are handled in 3.0.

Changes of IClipboardHelper

GraphClipboard

Folding API

Core Changes

Interface Updates

IFolderNodeConverter

IFoldingEdgeConverter

Behavior Changes

GraphML

Core Changes

API changes

Changes to class GraphMLIOHandler

The following classes, methods, and properties have been removed. Their functionality has been replaced by reasonable default values or moved to application logic:

The following classes, methods, and properties have been removed. Their functionality is now provided by the listed alternatives:

Changes to support classes and interfaces

Changes to the file format

import { configureGraphMLCompatibility } from 'graphml-compatibility/GraphMLCompatibility'
configureGraphMLCompatibility(graphMLIOHandler)

Noteworthy Layout Changes

Changed Names

Many API members have been renamed to achieve better consistency and uniformity throughout the entire API. The following tables list major renamings of algorithm/stage classes and other important classes. Warning: It is not a complete listing of name changes!

Changed Default Values

The following table lists the most important changes to default values.

Removed API

Important API members that are no longer part of yFiles for HTML 3.0 are listed in table Removed layout API members. Warning: this is not a complete list of removed API members!

Layout Data

The LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> used to specify custom data input for layout algorithms has become generic. It can no longer only be applied in conjunction with IGraph but also with LayoutGraph. This change means that the classes now have several generic type arguments that describe the type of items in the graph. See for example HierarchicalLayoutData.

Migrate existing usages

Instead of directly instantiating the data, you can now use the new factory methods on the algorithm instance, for example, createLayoutData.

const iGraph = new Graph()
const hierarchicalLayout = new HierarchicalLayout()

// create layout data for IGraph using factory method
const data = hierarchicalLayout.createLayoutData()

// ... and example usage of the created data
data.incrementalNodes.predicate = (iNode: INode) =>
  iNode.labels.size > 0
iGraph.applyLayout(hierarchicalLayout, data)

Using the creation methods is often more convenient. However, creating the layout data via the constructor is still possible.

// create layout data for IGraph using constructor
const data = new HierarchicalLayoutData<
  INode,
  IEdge,
  IModelItem,
  ILabel,
  ILabel
>()

You can now use the layout data when working with LayoutGraph in the same way.

const layoutGraph = new LayoutGraph()
const hierarchicalLayout = new HierarchicalLayout()

// create layout data for layoutGraph using factory method
const data = hierarchicalLayout.createLayoutData(layoutGraph)

// ... and example usage of the created data
data.incrementalNodes.predicate = (node: LayoutNode) =>
  node.labels.size > 0
layoutGraph.applyLayout(hierarchicalLayout, data)

Further changes

Layout Scope and Affected Items

The scope of a layout algorithm defines which graph elements are affected by the algorithm. yFiles for HTML 3.0 offers a more uniform scope API, designed to simplify the configuration of common use cases.

Restricting the Scope

The properties for restricting the scope of layout algorithms have been unified and, where possible, moved to the layout data. These layout data classes now offer a scope property, e.g., EdgeRouterData.scope, that supports any convenience that was previously offered on the layout algorithms, such as restricting affected edges by specifying incident nodes.

const edgeRouter = new EdgeRouter()
const edgeRouterData = edgeRouter.createLayoutData()
edgeRouterData.scope.incidentNodes.source = graphControl.selection.nodes

Convenience features that depend on an intermediate state of the layout, such as the EdgeRouter only handling broken paths, can now be assigned for individual elements through the Scope property.

edgeRouterData.scope.edgeMapping.mapperFunction = (edge: IEdge) =>
  edge.tag === 'Route if necessary'
    ? EdgeRouterScope.PATH_AS_NEEDED
    : EdgeRouterScope.IGNORE

The GenericLabeling algorithm is a notable exception to this general rule. While it supports the same ways of specifying the affected labels, it also retains functionality to restrict the algorithm to EdgeLabels or NodeLabels only on the labeling algorithm itself, since this use case was common enough to warrant a deviation from the norm. This convenience can theoretically be combined with a custom selection specified via the labeling data’s scope property to further restrict the affected labels. However, in such cases, it would be simpler and more maintainable to fully specify the scope on the layout data.

const genericLabeling = new GenericLabeling()
genericLabeling.scope = 'edge-labels'

Shared Scopes

In a layout pipeline that consists of multiple layout stages, it is often necessary for all algorithms to operate on the same subset of graph elements. Consequently, yFiles for HTML 3.0 introduces a single scope that only has to be set once for all layout algorithms. This replaces the individual scope-related data keys on the layout algorithms and affects all simple boolean states configurable through the layout data’s Scope properties, as well as values registered directly with the layout graph using the LayoutKeys:

As a result, writeable DataKeys such as RecursiveGroupLayout.InterEdgesDpKey and EdgeRouter.AffectedEdgesDataKey, that previously had to be manually synchronized to enable communication between the algorithms, are no longer necessary and were removed in yFiles for HTML 3.0. The communication between algorithms is now established automatically, using the new shared scope information.

However, scope information that relies on conditions more complex than a boolean value, such as OrganicScope, is still associated specifically with the corresponding layout algorithm.

For use cases where layout stages of the same layout pipeline must operate on different scopes, the ContextModificationStage can be used to temporarily change the data associated with any of the layout keys mentioned above, or even to temporarily apply an alternative layout data.

const edgeRouter = new EdgeRouter() // apply the straight line router immediately before the edge router
const edgeRouterData = edgeRouter.createLayoutData()
edgeRouterData.scope.edges.predicate = (e: IEdge) => e.tag === 'routed' // route marked edges

const straightLineRouter = new StraightLineEdgeRouter()
const contextModificationStage = new ContextModificationStage(
  straightLineRouter
) // temporarily change context for StraightLineRouter
contextModificationStage.addReplacementMap(
  LayoutKeys.ROUTE_EDGES_DATA_KEY,
  IMapper.fromHandler<LayoutEdge, boolean>(
    (e: LayoutEdge) => e.tag === 'straight-line'
  )
)

edgeRouter.coreLayout = contextModificationStage

Ports in Layout

General

In yFiles for HTML 3.0, the former concepts of PortConstraints and PortCandidates have been combined into a single, more powerful concept. A possible port (that is, the side or even the exact location where an edge connects to its source or target) is now represented by the class LayoutPortCandidate. Additionally, the valid sides of ports are now specified using the property side. The previous basic side values North, South, West, and East, provided by the enum PortSide have been renamed to TOP, BOTTOM, LEFT, and RIGHT, and are now defined in the enum PortSides.

The LayoutPortCandidate instances are typically not created directly but are instead part of NodePortCandidates (which are related to the former concept of PortCandidateSets) and EdgePortCandidates (which are related to the former concept of lists of PortCandidates). Most LayoutData classes for the major layout algorithm now have a ports property (for example, HierarchicalLayoutData.ports) that offer access to a new sub-data of type BasicPortData or PortData. These classes enable easy specification of port-related data for edges and nodes. Using class EdgePortCandidates demonstrates how to achieve this for different edges, and Using class NodePortCandidates shows how to specify the valid ports provided by a node.

// create the layout algorithm and the corresponding layout data instance
const layout = new HierarchicalLayout()
const data = layout.createLayoutData(graph)

// the 'ports' sub-data provides all port-related data;
// we want to specify the ports of edges on both endpoints (source and target)
const spcMapper = data.ports.sourcePortCandidates.mapper
const tpcMapper = data.ports.targetPortCandidates.mapper

// the source port of edge e1 should be at the center on the right side
// and the target port on the top or bottom side
spcMapper.set(
  e1,
  new EdgePortCandidates().addFixedCandidate('right', new Point(15, 0))
)
tpcMapper.set(
  e1,
  new EdgePortCandidates()
    .addFreeCandidate('top')
    .addFreeCandidate('bottom')
)

// the source port of edge e2 should be on the left side
// and on the target we want to keep the current port which is on the bottom side
spcMapper.set(e2, new EdgePortCandidates().addFreeCandidate('left'))
tpcMapper.set(e2, new EdgePortCandidates().addFixedCandidate('bottom'))

// specify some ports at the top side of node n1 ...
data.ports.nodePortCandidates.mapper.set(
  n1,
  new NodePortCandidates()
    .addFixedCandidate('top', new Point(-5, -15))
    .addFixedCandidate('top', new Point(5, -15), 3.0, 2)
)

// ... and a left and right port for node n2
data.ports.nodePortCandidates.mapper.set(
  n2,
  new NodePortCandidates()
    .addFreeCandidate('left', 2.0)
    .addFixedCandidate('right', new Point(15, 0))
)

Note that the former strong port constraints (enforcing that the layout algorithm keeps the current port location) can now be modeled with the method addFixedCandidate, that is, by creating a fixed candidate without specifying an offset.

The former class PortConstraintKeys has been removed. In most cases, the port data can simply be specified with the new port-related sub-data as mentioned above. If this is not possible, the data can still be specified and registered directly with the layout graph using the following data keys:

With yFiles for HTML 3.0, most layout algorithms provide at least generic support for ports. More precisely, for algorithms that do not directly support port candidates with an integrated approach, the ports are fixed as a post-processing step by automatically applying the class PortPlacementStage. Therefore, most of the algorithms’ LayoutData classes provide a port-related sub-data via the property ports (see BasicPortData and its usages).

Matching between node and edge port candidates

The layout algorithms automatically attempt to match appropriate node and edge port candidates. In yFiles for HTML 3.0, the matching process also considers the new matchingId parameter as shown in Creating matching port candidates. Two candidates can only be matched if their matching-ids are equal, or if at least one of the matching-ids is null (a `null`matching-id - which is the default - matches any other matching-id).

const layout = new HierarchicalLayout()
const data = layout.createLayoutData(graph)

// all nodes should provide two fixed ports at the top and bottom side;
// the available ports are subdivided into "red" and "blue" ports
data.ports.nodePortCandidates.constant = new NodePortCandidates()
  .addFixedCandidate({
    side: PortSides.TOP,
    offset: new Point(-5, -15),
    matchingId: 'red'
  })
  .addFixedCandidate({
    side: PortSides.TOP,
    offset: new Point(5, -15),
    matchingId: 'blue'
  })
  .addFixedCandidate({
    side: PortSides.BOTTOM,
    offset: new Point(-5, 15),
    matchingId: 'red'
  })
  .addFixedCandidate({
    side: PortSides.BOTTOM,
    offset: new Point(5, 15),
    matchingId: 'blue'
  })

const spcMapper = data.ports.sourcePortCandidates.mapper
const tpcMapper = data.ports.targetPortCandidates.mapper

// the source port of edge e1 can be any "red" port provided by the source node on its top side
spcMapper.set(
  e1,
  new EdgePortCandidates().addFreeCandidate({
    side: PortSides.TOP,
    matchingId: 'red'
  })
)

// the target port of edge e1 can be any port provided by the target node (matches each matchingId)
tpcMapper.set(
  e1,
  new EdgePortCandidates().addFreeCandidate({ side: PortSides.ANY })
)

// the source port of edge e2 can be any "blue" port provided by the source node
spcMapper.set(
  e2,
  new EdgePortCandidates().addFreeCandidate({
    side: PortSides.ANY,
    matchingId: 'blue'
  })
)

// the target port of edge e2 can be any port provided by the target node on its bottom side
tpcMapper.set(
  e2,
  new EdgePortCandidates().addFreeCandidate({ side: PortSides.BOTTOM })
)

Layout Duration and Aborting

While the two basic approaches to aborting the calculation of a graph layout have not changed, both approaches have received updated names to more accurately represent their usage and offer convenience improvements.

AbortHandler

The AbortHandler has been renamed to LayoutAbortController. The static methods to add or remove an abort controller to or from a graph have been removed. If necessary, a created abort controller can be registered directly with the LayoutGraph using the LayoutGraphContext property layoutAbortController. When starting a layout run via the LayoutExecutor, the run can be controlled via the properties cancelDuration and stopDuration.

Maximum Duration

The MaximumDuration property of layout algorithms that support early termination has been renamed to StopDuration to emphasize that it marks the time at which the layout algorithm begins the termination process. The termination itself can take additional time, as the algorithm still has to produce a consistent result. The type of the StopDuration property has been changed from a simple numeric value in a fixed unit (milliseconds) to TimeSpan, which supports specifying the duration in most common units of time.

Behavior Change

The ComponentLayout will no longer apply an abort controller’s stopDuration and cancelDuration to each component in full. Instead, the duration is now automatically split among the components based on their size.

Layout Stages and Multi-Stage Layouts

Some of yFiles’ more complex layout algorithms benefit from applying generalized pre- and post-processing stages. In yFiles for HTML 2.6, these algorithms implemented MultiStageLayout, which offered a framework to configure and execute the necessary stages. However, the inheritance introduced some conveniences for stages that were not helpful for a specific MultiStageLayout implementation. yFiles for HTML 3.0 replaces this inheritance-based approach by making a LayoutStageStack, as well as tailored convenience properties for accessing relevant stages, available on the respective algorithms. In addition, each ILayoutStage now offers an enabled property to conveniently enable or disable stages on the stack.

For more details also check the API documentation of the respective algorithm:

New Layout Graph API

With yFiles for HTML 3.0, the LayoutGraph API has been streamlined. Instead of using the Graph and LayoutGraph base classes with specific implementations, the LayoutGraph is now the sole graph model class. Concepts like the CopiedLayoutGraph are now implemented by methods such as createCopy.

Importantly, the API is now more similar to IGraph, making it easier for developers familiar with that part of yFiles. This primarily affects how you Accessing Graph Elements and Modifying the Graph Structure, but also includes the use of generic collections for graph elements instead of low-level datatypes like NodeList and EdgeList. As a result, you can query graph properties like the number of nodes and edges as properties of the nodes and edges collections.

Accessing Graph Elements

A goal of the layout graph rework in yFiles for HTML 3.0 was to make accessing graph elements more uniform, regardless of whether they are elements of a LayoutGraph or an IGraph. This results in the following changes:

Nodes

Edges

Labels

Labels have become fully-fledged layout graph elements of type LayoutNodeLabel and LayoutEdgeLabel with bounds, indices, customizable tags and a reference to their owner. Instead of accessing them from the layout graph, they can be retrieved directly via their owners’ LayoutNode.labels and LayoutEdge.labels properties.

More information on how to migrate to the new labeling API can be found in Labeling.

Examples

const graph = getMyGraph()

// Iterating the nodes and their labels
for (const node of graph.nodes) {
  // Do something with each node...
  for (const nodeLabel of node.labels) {
    // Do something with each label...
  }
}

// Iterating the edges of the graph
for (const edge of graph.edges) {
  // Do something with each edge...
}

// Get the first and last node of the node set from the graph.
const firstNode = graph.nodes.first
const lastNode = graph.nodes.last

// Check if some given node belongs to this graph.
const containsNode = graph.contains(node)

// Check if there is an edge between first and last node of the graph.
const containsEdge = graph
  .getEdgesBetween(graph.nodes.first()!, graph.nodes.last()!)
  .some()

Modifying the Graph Structure

      // get the first edge and node
      let firstEdge = graph.edges.first()!
      let firstNode = graph.nodes.first()!

      // remove the first edge and node
      graph.remove(firstEdge)
      graph.remove(firstNode)

      // get the new first edge and node
      firstEdge = graph.edges.first()!
      firstNode = graph.nodes.first()!

      // remove the first label of the node
      graph.remove(firstNode.labels.first()!)
      // remove the first bend of the edge's path
      graph.remove(firstEdge.bends.first()!)

      // Hide all edges which are part of some set/collection
      const graphHider = new LayoutGraphHider(graph)
      const edgesToHide = getEdgesToHideList()
      graphHider.hideEdges(edgesToHide)

      // now do something with the graph
      layoutAlgorithm.applyLayout(graph)

      // cleanup
      graphHider.unhideAll()

Copying the Graph

The yFiles for HTML 3.0 API no longer offers CopiedLayoutGraph as a LayoutGraph implementation specifically for copying an existing layout graph. Instead, LayoutGraph.createCopy can be used. This approach also replaces the removed BufferedLayout, though it should be noted that running a buffered layout is generally only necessary when applying custom layout code that relies on, for example, indices of nodes and edges staying consistent. Whenever a layout is applied to an IGraph instance, the layout is calculated on a layout graph that is created as a copy of the original graph. This provides the same conceptual benefits as a buffered layout run.

// copy the graph
const copiedGraph = LayoutGraph.createCopy(graph)
// apply a layout to the copied graph
layout.applyLayout(copiedGraph)
// write the calculated layout back to the original graph
copiedGraph.context.graphCopyData!.commitLayoutToOriginalGraph()

Structure Graph

For use cases where the graph structure must be analyzed, performance is often crucial. With yFiles for HTML 3.0, it’s possible to create a structure-only LayoutGraph designed to model only the graph structure and to ignore properties like positions or sizes of the elements. Such a graph can be created using the static createStructureGraph method of the LayoutGraph. Graphs created by this method can be used by all methods offered as LayoutGraphAlgorithms with the exception of findIntersections, which relies on coordinates.

The behavior of any method to query or change layout properties of a structure graph’s elements, as well as the behavior of any layout algorithm applied to a structure graph is undefined.

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:

These improvements are described in detail in Generic Labeling.

Labels in Custom Layouts

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.

Binding Data to a LayoutGraph

The new class LayoutGraphContext now manages all supplementary data for the graph and its elements, which can be used by layout algorithms during computation. Therefore, it replaces methods LayoutGraph.AddDataProvider and LayoutGraph.RemoveDataProvider of yFiles for HTML 2.6.

The interface IDataProvider has been removed. In yFiles for HTML 3.0, its replacement is the generic interface IMapper<K,V>.

Data Keys

Like before, data is stored on the graph using unique lookup key instances, typically defined by layout algorithms. Client code or LayoutData can supply additional data associated with a particular key. Layout algorithms can then retrieve this data using these keys and use it as input.

Keys are now called data keys. The base class for data keys is DataKey<TValue>. This class replaces the former DpKeyBase<TValue>. For items, like nodes and edges, there are specific keys, namely NodeDataKey<TValue> and EdgeDataKey<TValue>.

Data for Specific Items

// Create a mapper and set values for two specific edges
const edgeMapper = new Map<LayoutEdge, number>()
edgeMapper.set(edge1, 4.5)
edgeMapper.set(edge2, 1.0)

// Register the mapper using an existing DataKey
// Note: corresponds to old code graph.addDataProvider(EdgeThicknessDataKey)
graph.context.addItemData(
  HierarchicalLayout.EDGE_THICKNESS_DATA_KEY,
  edgeMapper
)

// ... Somewhere else: get the mapper from the graph
// Note: corresponds to old code graph.getDataProvider(EdgeThicknessDataKey)
const mapper = graph.context.getItemData(
  HierarchicalLayout.EDGE_THICKNESS_DATA_KEY
)

It is not required to always provide an IMapper<K,V>. Providing a getter/callback can be more convenient. This is a good replacement for code where in yFiles for HTML 2.6 a custom DataProviderAdapter was added.

// Add item data for nodes by using a getter/callback function
graph.context.addItemData(
  LayoutKeys.NODE_MARGIN_DATA_KEY,
  (node: LayoutNode) =>
    node.degree === 0 ? Insets.EMPTY : new Insets(10)
)

Global Data for the Graph

Previously, registering a single value with the LayoutGraph required using the IDataProvider interface, which has been removed. The DataProviders.CreateConstantDataProvider factory method was useful in that scenario. The replacement is the addData<TValue> method.

// Add a single rectangle as data using the key provided as first argument
graph.context.addData(
  ClearAreaLayout.EXPANDED_NODE_ORIGINAL_BOUNDS_DATA_KEY,
  new Rect(0, -20, 100, 200)
)

Amending and Removing Data

In previous versions of yFiles for HTML 2.6, temporarily changing, replacing, or removing data required manually removing an IDataProvider, addding a different one, and finally, once done, re-adding the original instance. While this approach is still possible, the new LayoutGraphContext now uses layers. Layers can be pushed onto and popped from the context. Pushing a layer creates a new layer, and any item data registered with a key on this new layer makes previously registered data invisible. This approach makes temporary changes much clearer.

// Push a new layer onto the context
graph.context.pushLayer()

// Register margins data, in this case defining a margin of 40 pixels for each node
graph.context.addItemData(
  LayoutKeys.NODE_MARGIN_DATA_KEY,
  (_) => new Insets(40)
)

// ... Do something, e.g., apply an algorithm. At this moment the 40 pixels margin is visible
new OrganicLayout().applyLayout(graph)

// Remove one context layer. This way the state will be equal to the original one. Margins are now as
// reset to whatever they were. It does not matter if margins were even registered or not.
graph.context.popLayer()

Grouping in the LayoutGraph

The grouping on the LayoutGraph is no longer defined by using data keys (GroupingKeys class in yFiles for HTML 2.6). Grouping information is now directly accessible by using methods on the graph instance itself:

Basic changes to the grouping can also be implemented using the graph and the following methods:

LayoutGraphGrouping

The LayoutGraphGrouping class replaces the (Layout)GroupingSupport class from yFiles for HTML 2.6 and offers more advanced grouping operations. You can create it using different factory methods, depending on whether you need a read-only or a writable instance. Additionally, it provides convenient methods such as checking if a graph is grouped at all (isGrouped).

When you need to query a lot of grouping information in performance-critical code, this approach is more efficient than accessing it through the graph instance.

In previous yFiles versions, you had to manually modify the data registered with the keys of GroupingKeys. Now, LayoutGraphGrouping offers methods to replace or hide the grouping structure. These operations can (and usually should) be undone later.

// given three nodes n1, n2, n3; n1 should be a group node that contains n2 and n3
// with this code we completely replace any previously defined grouping and define new relations
const grouping = LayoutGraphGrouping.replaceGrouping(graph)
grouping.setIsGroupNode(n1, true)
grouping.setParent(n2, n1)
grouping.setParent(n3, n1)

// ... other code

// finally, the replacement can be undone again
grouping.restore()

// hide the grouping so that the graph appears to contain no grouping at all
const hiddenGrouping = LayoutGraphGrouping.hideGrouping(graph)

// ... other code

// now, make it visible again
hiddenGrouping.restore()

Analysis Algorithms on the LayoutGraph

To execute analysis algorithms (e.g. shortest path, centrality measures) directly on a LayoutGraph, static methods are provided. In yFiles for HTML 2.6, the methods were thematically distributed among different types, for example, ShortestPaths, Centrality, Trees etc. Now, all algorithms are collected in the new class:

Furthermore, the signatures of the algorithm methods have been streamlined and simplified in many cases. When using an overload/signature that is not available anymore in yFiles for HTML 3.0, it will usually be possible to achieve the same again, but there is no generic recipe on how to migrate.

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

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

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.

Organic Layout

This section describes the major changes to the OrganicLayout.

Like all major layout algorithms, the OrganicLayout no longer inherits from MultiStageLayout but instead implements ILayoutAlgorithm directly. The layout stages are now managed by a LayoutStageStack, which can be obtained via the layoutStages property. See 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 the OrganicLayout. In addition to the changes listed here, the expert API was streamlined as well by removing some protected methods of OrganicLayout.

Changed Default Values and Behavior Changes

Node sizes are now always considered. Consequently, the property OrganicLayout.ConsiderNodeSizes has been removed.

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 the GenericLabeling algorithm by default. To change this behavior, set the edgeLabelPlacement property to the desired value.

The default component arrangement style has been changed from ROWS to PACKED_CIRCLE. The style can be specified via the ComponentLayout.style property. The ComponentLayout that is used by the OrganicLayout is available via the componentLayout property.

The OrganicLayout now always configures the ComponentLayout to respect the location of fixed nodes that lie in different components. The property SmartComponentLayout has been removed. To disable this configuration, replace the instance of the ComponentLayout in the LayoutStageStack accessible via the layoutStages property.

Port placement now takes the specified port candidates into account. The ports are placed in a post-processing step by the PortPlacementStage. Port candidates can be specified via the properties on the sub-data OrganicLayoutData.ports. See also the section Ports in Layout.

If custom clusters are defined via the OrganicLayoutData.clusterIds, these are considered automatically, and the value of OrganicLayout.clusteringPolicy is ignored. It is no longer necessary to set it to ClusteringPolicy.USER_DEFINED, which consequently has been removed.

ClassicOrganicLayout

The ClassicOrganicLayout has been superseded by the OrganicLayout, which supports all use cases of the ClassicOrganicLayout. Consequently, the ClassicOrganicLayout has been removed.

Scope

In yFiles for HTML 3.0, defining the scope has been made uniform for all major layout algorithms. For the OrganicLayout, this means that all settings related to the scope have been combined into the sub-data scope of the OrganicLayoutData.

Additionally, the scope mode can now be set per node, which makes it more flexible than before. To emulate the previous settings of the scope property of the OrganicLayout, the following settings can be used.

Constraints

The class ConstraintFactory has been removed. Node placement constraints should now be specified directly via the constraints property on the OrganicLayoutData, as when working with an IGraph.

const organicLayout = new OrganicLayout()
const layoutData = organicLayout.createLayoutData(graph)

// Align all nodes in the list on a horizontal line
layoutData.constraints.addAlignmentConstraint('horizontal').source =
  nodesToAlign

Interactive Organic Layout

The interactive organic layout has been significantly reworked. It is recommended to also consult the source code demo for the Interactive Organic Layout.

There is now a corresponding InteractiveOrganicLayoutData. This class is responsible for setting the value of the properties of the edges and nodes both before and during the layout calculations.

To set the initial values of these properties, it offers properties like preferredEdgeLengths. To update these values while the layout algorithm is running and to query the values that the algorithm used after completion, use handles (InteractiveOrganicNodeHandle and InteractiveOrganicEdgeHandle). For example, the method InteractiveOrganicLayout.SetPreferredEdgeLength has been replaced with the property InteractiveOrganicEdgeHandle.preferredEdgeLength. Mappings from the nodes to these handles are maintained by the InteractiveOrganicLayoutData using the properties nodeHandles and edgeHandles.

Orthogonal Layout

This chapter describes the major API changes to the OrthogonalLayout introduced with yFiles for HTML 3.0 and how to migrate from the older version.

As with all major layout algorithms, the OrthogonalLayout no longer inherits from MultiStageLayout, but implements ILayoutAlgorithm directly. The layout stages are now managed by a LayoutStageStack, which can be obtained via the layoutStages property; see 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 the OrthogonalLayout. In addition to the changes listed here, the expert API was also streamlined by removing some protected methods of OrthogonalLayout.

Changed Default Values and Behavior Changes

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

Edge labels are now considered by default. To revert to the previous 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.

Port placement now takes the specified port candidates into account. The ports are placed in a post-processing step by the PortPlacementStage. Port candidates can be specified via the properties on the sub-data OrthogonalLayoutData.ports. See also the section Ports in Layout.

Tree Layout

This chapter describes the major API changes to the TreeLayout introduced with yFiles for HTML 3.0 and how to migrate from the older version.

As with all major layout algorithms, the TreeLayout no longer inherits from MultiStageLayout, but instead implements ILayoutAlgorithm directly. 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 contains the renamed, moved, and removed classes and members of the major classes of the TreeLayout.

Changed Default Values and Behavior Changes

If non-tree graphs are given as input, they are now temporarily reduced to trees by applying the TreeReductionStage before applying the layout algorithm. The non-tree edges are then routed using the router specified via the TreeReductionStage.nonTreeEdgeRouter. The TreeReductionStage that is used by the TreeLayout is available via the property TreeLayout.treeReductionStage.

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 the node labels with GenericLabeling by setting the value to GENERIC.

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

The port assignment modes specified via the property TreeLayoutPortAssigner.mode have been reduced. Port candidates are now always considered. It is no longer necessary to set it to PORT_CONSTRAINT. The distributed values for the four sides of the node have been combined as DISTRIBUTED. The side can be specified by defining a free port candidate on the desired side via the properties on TreeLayoutData.ports. See also section Ports in Layout for more information.

The MultiLayerSubtreePlacer (formerly GridNodePlacer) now automatically considers custom layers defined via the property multiLayerSubtreePlacerLayerIndices. It is no longer necessary to set the property automaticRowAssignment, which has consequently been removed.

Classic Tree Layout

The ClassicTreeLayout has been superseded by the TreeLayout. To obtain similar results within a similar time frame, the following configuration may be used.

const subtreePlacer = new LevelAlignedSubtreePlacer()
subtreePlacer.alignPorts = false // required (default)
subtreePlacer.busAlignment = 0.6 // can be changed freely
subtreePlacer.dendrogramStyle = false // required (default)
subtreePlacer.layerSpacing = layerDistance // can be changed freely
subtreePlacer.polylineLabeling = false // required (default)
subtreePlacer.rootAlignment = SubtreeRootAlignment.CENTER_OF_PORTS // required
subtreePlacer.edgeRoutingStyle =
  LevelAlignedSubtreePlacerRoutingStyle.ORTHOGONAL // or StraightLine
subtreePlacer.spacing = nodeDistance // should be at most BusAlignment * LayerSpacing
subtreePlacer.verticalAlignment = 0.5 // required (default)

const treeLayout = new TreeLayout({
  defaultSubtreePlacer: subtreePlacer
})

Aspect Ratio Tree Layout

The AspectRatioTreeLayout has been superseded by the TreeLayout with the AspectRatioSubtreePlacer. To obtain similar results, use the following configuration, which depends on the previous value of the rootPlacement.

const subtreePlacer = new AspectRatioSubtreePlacer({
  childArrangement: childArrangement,
  rootPlacement: rootPlacement
})

const treeLayout = new TreeLayout({
  defaultSubtreePlacer: subtreePlacer
})

Major Changes to Expert API

Several protected methods of the TreeLayout class have been removed. In many case, these protected methods allowed for customizations that are better handled by setting appropriate values through the appropriate TreeLayoutData properties. The remaining methods still allow extensive customization of the layout process.

Radial Tree Layout (formerly: Balloon Layout)

This chapter describes the major API changes to the RadialTreeLayout (formerly called BalloonLayout) introduced with yFiles for HTML 3.0 and how to migrate from the older version.

Like all major layout algorithms, the class no longer inherits from MultiStageLayout, but implements ILayoutAlgorithm directly. 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 the RadialTreeLayout.

Changed Default Values and Behavior Changes

If non-tree graphs are provided as input, the layout algorithm now temporarily reduces them to trees by applying the TreeReductionStage. The non-tree edges are then routed using the router specified via the TreeReductionStage.nonTreeEdgeRouter. The TreeReductionStage used by the RadialTreeLayout is accessible via the property RadialTreeLayout.treeReductionStage.

The from-sketch mode (ordering policy FROM_SKETCH) does no longer take precedence over orders specified via layout data properties childOrder or nodeTypes.

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 the node labels with GenericLabeling by setting the value to GENERIC.

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

The default component arrangement style has been changed to PACKED_CIRCLE. The style can be specified via the ComponentLayout.style property. The ComponentLayout used by the RadialTreeLayout is accessible via the componentLayout property.

The compactnessFactor is now interpreted differently. Larger values now produce more compact layouts. The range of the compactness factor has been changed to the interval between 0 and 1.

Major Changes to Expert API

Several methods for advanced customization of the layout result have been removed from the API, including calculateChildArrangement and calculateAngles. Overriding these methods should not have been necessary. To customize the preferred sector angles, the callback method getPreferredChildSectorAngle is still available.

The helper class BalloonLayoutNodeInfo has also been removed. It was only necessary and useful during the layout process and when overriding advanced methods that have now been removed.

Radial Layout

This section describes the major changes to the RadialLayout class.

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

Renamed, Moved, and Removed Classes and Members

The following table contains the renamed, moved, and removed classes and members of the major classes of the RadialLayout.

Changed Default Values and Behavior Changes

Node labels are now considered by default. To change this behavior, set the nodeLabelPlacement property to the desired value. This property allows switching between all integrated node labeling policies and placing the node labels with GenericLabeling.

Edge labels are now placed by the GenericLabeling algorithm by default. To change this behavior, set the edgeLabelPlacement property to the desired value.

Port placement now takes the specified port candidates into account. Port candidates can be specified via the properties on the sub-data RadialLayoutData.ports. The ports are placed in a post-processing step by the PortPlacementStage.

If custom layers are defined via the RadialLayoutData.layerIds property, these are considered automatically, and the value of RadialLayout.layeringStrategy is ignored. It is no longer necessary to set it to RadialLayoutLayeringStrategy.USER_DEFINED, which consequently has been removed.

If custom center nodes are defined via the RadialLayoutData.centerNodes property, these are considered automatically, and the value of RadialLayout.centerNodesPolicy is ignored. It is no longer necessary to set it to CenterNodesPolicy.CUSTOM, which consequently has been removed.

Radial Group Layout (formerly: Cactus Group Layout)

This section describes the major API changes to the RadialGroupLayout (formerly CactusGroupLayout).

As with all major layout algorithms, the RadialGroupLayout no longer inherits from MultiStageLayout. Instead, it implements ILayoutAlgorithm directly. The layout stages are now managed by a LayoutStageStack, which can be obtained via the layoutStages property. See 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 the RadialGroupLayout.

Changed Default Values and Behavior Changes

Edge labels are now placed by the GenericLabeling algorithm by default. To change this behavior, set the edgeLabelPlacement property to the desired value.

Port placement now takes the specified port candidates into account. The ports are placed in a post-processing step by the PortPlacementStage. Port candidates can be specified via the properties on the sub-data RadialGroupLayoutData.ports. See also the section Ports in Layout.

The default value of preferredRootSectorAngle has been changed from 180 degrees to 360 degrees.

Circular Layout

This chapter describes the major API changes to the yWorks.Layout.Circular.CircularLayout introduced with yFiles for HTML 3.0 and how to migrate from the older version.

As with all major layout algorithms, the CircularLayout no longer inherits from MultiStageLayout, but implements ILayoutAlgorithm directly. The layout stages are now managed by a LayoutStageStack, which can be obtained via the layoutStages property; see 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 the CircularLayout. In addition to the changes listed here, the expert API was streamlined by removing some protected methods of CircularLayout.