jsPlumb Community Edition Documentation

A Connection in jsPlumb is the primary abstraction representing the link between two elements. It is composed of several constituent parts:

• Endpoint: The visual representation of one end of a connection. You can create them manually (required for drag-and-drop support) or let jsPlumb create them via jsPlumb.connect(...).
• Anchor: A logical position relative to an element's origin where an Endpoint exists. Anchors have no visual representation and are created automatically based on hints you provide.
• Connector: The visual line (e.g., Bezier curve, straight line, flowchart, or state machine) that joins two Endpoints.
• Overlay: UI components used to decorate a Connector, such as Labels or Arrows.
• Group: A container for a set of elements that can be collapsed, causing all connections to group members to be pooled onto the group container.

Relationship Model: One Connection = 2 Endpoints + 1 Connector + zero or more Overlays. Each Endpoint is associated with an Anchor.

Interceptors are specialized event handlers that allow you to abort jsPlumb actions by returning false. They act as gatekeepers for connection lifecycle events.

Registration Methods

You can register interceptors in two ways:

1. Global Binding: Use jsPlumbInstance.bind(interceptorName, callback) to create a catch-all handler. For example, a global beforeDrop will trigger for any connection dropped on any endpoint unless that specific endpoint has its own interceptor.
2. Local Configuration: Pass interceptor callbacks directly into methods like addEndpoint, makeSource, or makeTarget to constrain the interceptor to a specific element or endpoint.

Supported Interceptors

• beforeDrop: Triggered when a connection is dropped onto a target.
• beforeDetach: Triggered when a connection is being detached (e.g., dragged off an endpoint into whitespace).
• beforeDrag: Triggered when a user starts dragging a new connection from an endpoint.
• beforeStartDetach: Triggered when a user starts dragging an existing connection off an endpoint.

Scopes control which draggables can be dropped on which droppables. A draggable can only be dropped on a droppable if they share the same scope.

• Default Scope: Accessible via jsPlumb.getDefaultScope(). Set it via jsPlumb.setDefaultScope(string).
• Multiple Scopes: You can assign multiple scopes to an endpoint or element by providing a space-separated string (similar to CSS classes).
• Setting Scopes: Use setScope(el, scope), setSourceScope(el, scope), or setTargetScope(el, scope) to update an existing configuration.
• Drag/Drop Options: You can pass scope through dragOptions and dropOptions to the underlying library.

// Assigning multiple scopes
var options = {
  scope: "foo bar baz"
};

// Providing scope via drag/drop options
var options = {
  dragOptions: { scope: "dragScope" },
  dropOptions: { scope: "dropScope" }
};

// Changing scope of an existing element
jsPlumb.setSourceScope("el1", "newScope");

jsPlumb provides several interceptor types that allow you to programmatically control or modify connection lifecycle events. These are useful for implementing validation logic, such as preventing certain connections or modifying drag parameters.

Key interceptor types include:

• BeforeDragInterceptor: Intercepts a drag operation. Returning false cancels the drag. Returning a Record<string, any> allows you to pass additional data to the drag operation.
• BeforeDropInterceptor: Intercepts a drop operation. Returning false prevents the connection from being established.
• BeforeDetachInterceptor: Intercepts the detachment of a connection. Returning false prevents detachment.
• BeforeStartDetachInterceptor: Intercepts the start of a detachment process.

// Example: Preventing a connection if certain conditions aren't met
instance.registerInterceptor('beforeDrop', (params: BeforeDropParams) => {
  const { connection, targetId, sourceId } = params;
  // Logic to decide if connection is allowed
  return targetId !== 'forbidden-zone';
});