Reconnecting Edges

Edge reconnection involves moving an edge’s source or target endpoint to another port. In yFiles for HTML, this is accomplished by selecting an edge and dragging the handle that represents its source or target port. Edge reconnection is enabled by default, and edges can be reconnected to the port candidates provided for nodes.

The following steps occur when reconnecting edges:

These steps can be adjusted for a customized reconnection behavior. The most common adjustments include Providing Port Candidates and Customizing the Reconnection Gesture.

Providing Port Candidates

Possible candidates for new source and target nodes are provided by implementations of IEdgeReconnectionPortCandidateProvider which are retrieved from the edge’s lookup. During reconnections, the following methods are called to return a list of port candidates:

Implementers must implement the above methods to return an appropriate list of candidates. Note that this list may be empty (or contain only invalid candidates) if an edge cannot be reconnected. The concept of port candidates is explained above.

yFiles for HTML provides several IEdgeReconnectionPortCandidateProvider implementations for common use cases. These are available through factory methods or constants on the IEdgeReconnectionPortCandidateProvider interface:

The edge’s lookup must be modified to return an instance of the new provider. You can do this using an EdgeDecorator:

graph.decorator.edges.reconnectionPortCandidateProvider.addFactory(
  IEdgeReconnectionPortCandidateProvider.fromSourceAndTarget
)

The tutorial demo application Edge Reconnection shows how to implement IEdgeReconnectionPortCandidateProvider for different purposes.

Customizing the Reconnection Gesture

The actual dragging is managed by IHandle implementations, and by default, a PortRelocationHandle is used. It provides a number of settings that control the behavior and appearance of the handle. The most common settings are listed below:

Additionally, the maximum distance the pointer can be from a candidate to snap to it can be set via maximumSnapDistance.

The appearance of the edge during the movement gesture can be determined with visualization. The effect is visualized below. The default is PLACEHOLDER:

The PortRelocationHandle cannot be directly associated with edges. Instead instances of this IHandle are provided by the PortRelocationHandleProvider. It can be associated using the edges's portHandleProvider. The most commonly used settings are also available on the PortRelocationHandleProvider:

graph.decorator.edges.portHandleProvider.addFactory((edge) => {
  const portRelocationHandleProvider = new PortRelocationHandleProvider(
    graph,
    edge
  )
  portRelocationHandleProvider.visualization = Visualization.LIVE
  portRelocationHandleProvider.showPortCandidates = false
  return portRelocationHandleProvider
})

For less frequently used settings, a custom PortRelocationHandleProvider has to be provided, and its createPortRelocationHandle method must be overridden to provide the configured PortRelocationHandle:

graph.decorator.edges.portHandleProvider.addFactory((edge) => {
  const portRelocationHandleProvider = new MyHandleProvider(graph, edge)
  portRelocationHandleProvider.visualization = Visualization.LIVE
  portRelocationHandleProvider.showPortCandidates = false
  return portRelocationHandleProvider
})

class MyHandleProvider extends PortRelocationHandleProvider {
  createPortRelocationHandle(
    graph: IGraph,
    edge: IEdge,
    sourceEnd: boolean
  ): PortRelocationHandle {
    const portRelocationHandle = new PortRelocationHandle(
      graph,
      edge,
      sourceEnd
    )
    portRelocationHandle.addExistingPort = true
    return portRelocationHandle
  }
}