jsPlumb

What’s new in jsPlumb 1.2.6

jsPlumb 1.2.6 was released today, with several bugfixes, an improved syntax for specifying Endpoints, Connectors and Overlays, mouse events when using Canvas, Flowchart Connectors, and a couple of other new pieces of functionality.  Here’s a run-down.

Shorthand Syntax for Endpoints, Connectors and Overlays

In previous versions of jsPlumb you may have got used to writing code like this:

jsPlumb.connect({
  source:"someDiv",
  target:"someOtherDiv",
  connector:new jsPlumb.Connectors.Bezier(68),
  endpoints:[ new jsPlumb.Endpoints.Dot({radius:12}),
              new jsPlumb.Endpoints.Rectangle({width:20, height:30}) 
  ]
});

That’s a lot of typing. 1.2.6 introduces a shorthand syntax designed to reduce the incidence of RSI amongst jsPlumb users. The equivalent code now looks like this:

jsPlumb.connect({
  source:"someDiv",
  target:"someOtherDiv",
  connector:["Bezier",68],
  endpoints:[["Dot",{radius:12}], ["Rectangle",{width:20,height:30}]]
});

If you are happy using the default parameter values for some component, you can use an even terser syntax:

jsPlumb.connect({
  source:"someDiv",
  target:"someOtherDiv",
  connector:"Bezier",
  endpoints:[ "Dot", "Rectangle" ]
});

The same syntax can be used for Overlays. For instance, you used to write something like:

jsPlumb.connect({
  source:"someDiv",
  target:"someOtherDiv",
  overlays:[
   new jsPlumb.Overlays.Arrow({location:0.1, width:10}),
   new jsPlumb.Overlays.Label({label:"foo", location:0.6})
  ]
});

which now would look like this:

jsPlumb.connect({
  source:"someDiv",
  target:"someOtherDiv",
  overlays:[
   [ "Arrow", {location:0.1, width:10} ],
   [ "Label", {label:"foo", location:0.6} ]
  ]
});

The same terser syntax applies to Overlays, if you are happy to be using the defaults, as it does for Endpoints and Connectors.

Flowchart Connectors

These are what the name suggests: connectors that consist of a series of horizontal or vertical segments, as you’d see on a flowchart. They support one parameter, minStubLength, which tells jsPlumb what the shortest acceptable value is for the stub that begins each connection.

To use these, taking the example code from above, you’d do this:

jsPlumb.connect({
  source:"someDiv",
  target:"someOtherDiv",
  connector:[ "Flowchart", {minStubLength:40} ],
  endpoints:[ "Dot", "Rectangle" ]
});

Note that here I have set the ‘minStubLength’ argument to tell jsPlumb the stubs need to be at least 40px long. This will make more sense if you checkout the demo.

Mouse Events

1.2.6 introduces support for the following mouse events, but only when you’re using Canvas, meaning not in IE prior to version 9.  The next release of jsPlumb will support mouse events for all browsers.

• click
• dblclick
• mouseenter
• mouseexit

Handlers for these events can be registered on Endpoints and Connectors, using the bind method:

var connection = jsPlumb.connect(...some options...);
connection.bind("click", function(c) {
  console.log("c is a Connection object.  it connects " + c.sourceId + " to " + c.targetId);
});

As I was about to release 1.2.6 I realised, from using the API myself, that it would probably be more convenient to be able to bind a click handler on jsPlumb itself, to be notified of click events on any Endpoint or Connector. This functionality will be included in the next jsPlumb release.

This new functionality allows jsPlumb to support ‘hover’ styles for Endpoints and Connections - just like the CSS :hover pseudo class. For example:

jsPlumb.connect({
  source:"someDiv", 
  target:"someOtherDiv",
  paintStyle:{strokeStyle:"blue", lineWidth:5},
  hoverPaintStyle:{strokeStyle:"red", lineWidth:7}
});

Acceptable arguments for ‘hoverPaintStyle’ are whatever is acceptable for ‘paintStyle’.

Miscellaneous bits & pieces

• The jQuery plugin methods have been removed. They were never kept fully up to date anyway, and then jQuery introduced a ‘detach’ method in 1.5 which clashed with jsPlumb’s existing detach method. So they have all been removed.
• Connection and Endpoint now have a ‘setPaintStyle’ method, which sets a new paint style and then repaints the component.
• Connection has a ‘setBackgroundPaintStyle’ method which does the same thing, for the Connection’s background.
• The Arrow Overlay supports a ‘direction’ parameter now. Valid values are 1 (the default), which means point forwards, and -1, which means point backwards.
• Arrow Overlays derive their fill style automatically from the stroke style of their Connector if no fillStyle is supplied
• The Label Overlay passes in its associated Connection to the registered labelling function, if you’re using one.
• jsPlumb.connect takes an optional second argument, which you can use to supply values that are common between Connections. You may have written something like this:

  var opts = { 
    paintStyle:{ strokeStyle:"red" }
  };
  jsPlumb.connect(jsPlumb.extend({ source:"div1", target:"div2" }, opts));
  jsPlumb.connect(jsPlumb.extend({ source:"div3", target:"div4" }, opts));
  

  you can now do this:

  var opts = { 
    paintStyle:{ strokeStyle:"red" }
  };
  jsPlumb.connect({ source:"div1", target:"div2" }, opts);
  jsPlumb.connect({ source:"div3", target:"div4" }, opts);
  

  ie. jsPlumb automatically does the ‘extend’ call for you.
• jsPlumb.addEndpoint takes an optional third argument, which you can use to supply values that are common between Endpoints. You may have written something like this:

  var opts = { 
    paintStyle:{ fillStyle:"red" }
  };
  jsPlumb.addEndpoint("div1", jsPlumb.extend({ anchor:"TopMiddle" }, opts));
  jsPlumb.addEndpoint("div2", jsPlumb.extend({ anchor:"BottomMiddle" }, opts));
  

  you can now do this:

  var opts = { 
    paintStyle:{ strokeStyle:"red" }
  };
  jsPlumb.addEndpoint("div1", { anchor:"TopMiddle" }, opts);
  jsPlumb.addEndpoint("div2", { anchor:"BottomMiddle" }, opts);
  

• added jsPlumb.bind(“ready”, function() { … } ). You should use this instead of the underlying library’s DOM ready functionality to get a callback to start working with jsPlumb. If you use YUI it is imperative that you use this instead of Y.on(“domready”…), because of the asynchronous nature of the way YUI loads JS. For jQuery and MooTools its more of a question of good style: you’re explicitly handing off control to jsPlumb to tell you when it is ready for you to use it.