DEMOS
DOCS
FEATURES
DOWNLOAD
PURCHASE
CONTACT
BLOG

Events

jsPlumb supports binding to several different events on Connections, Endpoints and Overlays, and also on the jsPlumb object itself.

jsPlumb Events

To bind an to event on jsPlumb itself (or a jsPlumb instance), use jsPlumb.bind(event, callback):

jsPlumb.bind("connection", function(info) {
   .. update your model in here, maybe.
});

These are the events you can bind to on the jsPlumb class:

connection(info, originalEvent)

Notification a Connection was established.

info is an object with the following properties:

  • connection - the new Connection. you can register listeners on this etc.
  • sourceId - id of the source element in the Connection
  • targetId - id of the target element in the Connection
  • source - the source element in the Connection
  • target - the target element in the Connection
  • sourceEndpoint - the source Endpoint in the Connection
  • targetEndpoint - the targetEndpoint in the Connection

Note: jsPlumb.connect causes this event to be fired, but there is of course no original event when a connection is established programmatically. So you can test to see if originalEvent is undefined to determine whether a connection was estblished using the mouse or not.

All of the source/target properties are actually available inside the Connection object, but - for one of those rubbish historical reasons - are provided separately because of a vagary of the connectionDetached callback, which is discussed below.

connectionDetached(info, originalEvent)

Notification a Connection was detached.

As with connection, the first argument to the callback is an object with the following properties:

  • connection - the Connection that was detached.
  • sourceId - id of the source element in the Connection before it was detached
  • targetId - id of the target element in the Connection before it was detached
  • source - the source element in the Connection before it was detached
  • target - the target element in the Connection before it was detached
  • sourceEndpoint - the source Endpoint in the Connection before it was detached
  • targetEndpoint - the targetEndpoint in the Connection before it was detached

This event is not fired when a newly dragged Connection is abandoned before being connected to something. To catch that, use connectionAborted.

The source/target properties are provided separately from the Connection, because this event is fired whenever a Connection is either detached and abandoned, or detached from some Endpoint and attached to another. In the latter case, the Connection that is passed to this callback is in an indeterminate state (that is, the Endpoints are still in the state they are in when dragging, and do not reflect static reality), and so the source/target properties give you the real story.

The second argument is the original mouse event that caused the disconnection, if any.

connectionMoved(info, originalEvent)

Notification that an existing connection's source or target endpoint was dragged to some new location. info contains the following properties:

  • index - 0 for source endpoint, 1 for target endpoint
  • originalSourceId - id of connection source element before move
  • newSourceId - id of connection source element after move
  • originalTargetId id of connection target before move
  • newTargetId - id of connection target after move
  • originalSourceEndpoint - source endpoint before move
  • newSourceEndpoint - source endpoint after move
  • originalTargetEndpoint - target endpoint before move
  • newTargetEndpoint - target endpoint after move

connectionAborted(connection, originalEvent)

Fired when a new Connection is dragged but abandoned before being connected to an Endpoint or a target element.

connectionDrag(connection)

Notification an existing Connection is being dragged. Note that when this event fires for a brand new Connection, the target of the Connection is a transient element that jsPlumb is using for dragging, and will be removed from the DOM when the Connection is subsequently either established or aborted.

connectionDragStop(connection)

Notification a Connection drag has stopped. This is only fired for existing Connections.

click(connection, originalEvent)

Notification a Connection was clicked.

dblclick(connection, originalEvent)

Notification a Connection was double-clicked.

endpointClick(endpoint, originalEvent)

Notification an Endpoint was clicked.

endpointDblClick(endpoint, originalEvent)

Notification an Endpoint was double-clicked.

contextmenu(component, originalEvent)

A right-click on some given component. jsPlumb will report right clicks on both Connections and Endpoints.

beforeDrop(info)

This event is fired when a new or existing connection has been dropped. info contains the following properties:

  • sourceId - the id of the source element in the connection
  • targetId - the id of the target element in the connection
  • scope - the scope of the connection
  • connection - the actual Connection object. You can access the 'endpoints' array in a Connection to get the Endpoints involved in the Connection, but be aware that when a Connection is being dragged, one of these Endpoints will always be a transient Endpoint that exists only for the life of the drag. To get the Endpoint on which the Connection is being dropped, use the dropEndpoint member.
  • dropEndpoint - this is the actual Endpoint on which the Connection is being dropped. This may be null, because it will not be set if the Connection is being dropped on an element on which makeTarget has been called.

If you return false (or nothing) from this callback, the new Connection is aborted and removed from the UI.

beforeDetach(connection)

This event is fired when a Connection is about to be detached, for whatever reason. Your callback function is passed the Connection that the user has just detached. Returning false from this interceptor aborts the Connection detach.

zoom(value)

Notification the current zoom was changed.

Connection Events

To bind to an event on a Connection, you also use the bind method:

var connection = jsPlumb.connect({source:"d1", target:"d2"});
connection.bind("click", function(conn) {
    console.log("you clicked on ", conn);
});

These are the Connection events to which you can bind a listener:

  • click(connection, originalEvent) - notification a Connection was clicked.

  • dblclick(connection, originalEvent) - notification a Connection was double-clicked.

  • contextmenu(connection, originalEvent) - a right-click on the Connection.

  • mouseover(connection, originalEvent) - notification the mouse is over the Connection's path.

  • mouseout(connection, originalEvent) - notification the mouse has exited the Connection's path.

  • mousedown(connection, originalEvent) - notification the mouse button was pressed on the Connection's path.

  • mouseup(connection, originalEvent) - notification the mouse button was released on the Connection's path.

Endpoint Events

To bind to an event on a Endpoint, you again use the bind method:

var endpoint = jsPlumb.addEndpoint("d1", { someOptions } );
endpoint.bind("click", function(endpoint) {
    console.log("you clicked on ", endpoint);
});

These are the Endpoint events to which you can bind a listener:

  • click(endpoint, originalEvent) - notification an Endpoint was clicked.

  • dblclick(endpoint, originalEvent) - notification an Endpoint was double-clicked.

  • contextmenu(endpoint, originalEvent) - a right-click on the Endpoint.

  • mouseover(endpoint, originalEvent) - notification the mouse is over the Endpoint.

  • mouseout(endpoint, originalEvent) - notification the mouse has exited the Endpoint.

  • mousedown(endpoint, originalEvent) - notification the mouse button was pressed on the Endpoint.

  • mouseup(endpoint, originalEvent) - notification the mouse button was released on the Endpoint.

  • maxConnections(info, originalEvent) - notification the user tried to drop a Connection on an Endpoint that already has the maximum number of Connections. info is an object literal containing these values:

    • endpoint : Endpoint on which the Connection was dropped
    • connection : The Connection the user tried to drop
    • maxConnections : The value of maxConnections for the Endpoint

Overlay Events

Registering event listeners on an Overlay is a slightly different procedure - you provide them as arguments to the Overlay's constructor. This is because you never actually act on an Overlay object.

Here's how to register a click listener on an Overlay:

jsPlumb.connect({
    source:"el1",
    target:"el2",
    overlays:[
      [ "Label", {
        events:{
          click:function(labelOverlay, originalEvent) { 
            console.log("click on label overlay for :" + labelOverlay.component); 
          }
        }
      }],
      [ "Diamond", {
        events:{
          dblclick:function(diamondOverlay, originalEvent) { 
            console.log("double click on diamond overlay for : " + diamondOverlay.component); 
          }
        }
      }]    
    ]
  });

The related component for an Overlay is available to you as the component member of the Overlay.

Unbinding Events

On the jsPlumb object and on Connections and Endpoints, you can use the unbind method to remove a listener. This method either takes the name of the event to unbind:

jsPlumb.unbind("click");

...or no argument, meaning unbind all events:

var e = jsPlumb.addEndpoint("someDiv");
e.bind("click", function() { ... });
e.bind("dblclick", function() { ... });

...

e.unbind("click");