HTMLGraph | Features | Connectable Ports

Connectable Ports

In some use cases, providing users with interactive graph modification functionality is essential. Part of this functionality is the ability to add new connections to the graph.

To enable ports that are connectable via dragging, call the enableUserConnectablePorts method on a CanvasBuilder instance:

    
const element = document.getElementById(&#34;canvas&#34;);

const canvas = new CanvasBuilder(element)
  .enableUserConnectablePorts()
  .build();

It is crucial for a port to have a “grabable” area large enough to actually be grabbed by the user, as shown in the example below.

The enableUserConnectablePorts method accepts optional configuration.

Configuration Parameters

Name	Type	Description	Required	Default
`connectionTypeResolver`	`(portId) => "direct" \| "reverse" \| null`	Resolves connection type when edge creation has been initiated. `null` means that connection is disallowed	no	`() => "direct"`
`connectionAllowedVerifier`	`(request: { from: Identifier, to: Identifier }) => boolean`	Verifies if connection between specified ports is allowed.	no	`(request) => true`
`dragPortDirection`	`DragPortDirection`	Direction of dragging port	no	`"inherit"`
`connectionPreprocessor`	`(request: AddEdgeRequest) => AddEdgeRequest`	Applies modifications to the edge about to be created.	no	`(request) => request`
`grabbedPortIdResolver`	`(portIds: Identifier[]) => Identifier \| null`	Resolves ID of a port being grabbed when there’s ambiguity. See `PortIdResolver`	no	First added port
`releasedPortIdResolver`	`(portIds: Identifier[]) => Identifier \| null`	Resolves ID of a port being released when there’s ambiguity. See `PortIdResolver`	no	First added port
`mouseDownEventVerifier`	`(event) => boolean`	Function to verify if mouse event should initiate connection creation process	no	`(event) => event.button === 0`
`mouseUpEventVerifier`	`(event) => boolean`	Function to verify if mouse event should create connection	no	`(event) => event.button === 0`
`edgeShape`	`EdgeShapeConfig`	Default edge shape configuration while port is in the process of dragging	no	Same as for canvas
`events`	`EventsConfig`	Handlers for available events	no	`{}`

Here’s a good example of a reasonable connection type resolver, which resolves direct connection when an “out” port gets grabbed, and reverses connection when an “in” port gets grabbed:

    
const connectionTypeResolver = (portId) =&gt; {
  return portId.endsWith(&#34;-out&#34;) ? &#34;direct&#34; : &#34;reverse&#34;;
};

As for the connection allowed verifier, you can start with one that forbids duplicated connections:

    
const connectionAllowedVerifier = (request) =&gt; {
  const existingEdge = canvas.graph.getAllEdgeIds().find((edgeId) =&gt; {
    const edge = canvas.graph.getEdge(edgeId);

    return edge.from === request.from &amp;&amp; edge.to === request.to;
  });

  return existingEdge === undefined;
};

`DragPortDirection`

Name	Type	Description
Constant	`number`	Fixed radian angle for the dragging port direction
Nearest Connectable Port	`"nearest-connectable-port"`	Direction matches the direction of the nearest connectable port
Inherit	`"inherit"`	Direction matches the original direction of the port being grabbed

`PortIdResolver`

The same element can be marked as multiple different ports. When user interacts with such element, it’s not clear which port should be interacted with, for example when grabbed or released.

PortIdResolver function allows to configure such behavior.

There are good examples of such functions:

    
const grabbedPortIdResolver = (portIds) =&gt; {
  return portIds.find((portId) =&gt; portId.endsWith(&#34;-out&#34;)) ?? null;
}

const releasedPortIdResolver = (portIds) =&gt; {
  return portIds.find((portId) =&gt; portId.endsWith(&#34;-in&#34;)) ?? null;
}

`EventsConfig`

Name	Type	Description	Required	Default
`onAfterEdgeCreated`	`(edgeId) => void`	Function called after a new edge has been added	no	`() => void`
`onEdgeCreationInterrupted`	`(params: { staticPortId, isDirect: boolean}) => void`	Function called when edge creation is interrupted in the process	no	`() => void`
`onEdgeCreationPrevented`	`(request: AddEdgeRequest) => void`	Function called when an attempt to create edge is prevented	no	`() => void`

You might also be interested in the Edges with Remove Button tutorial.