jsPlumb

jsPlumb basics

In this post I’m going to attempt to provide you with a basic overview of the concepts used by the jsPlumb plugin.  If jsPlumb is new to you then maybe you might want to take a look here:

http://jplumb.org

In a nutshell, jsPlumb offers you the ability to visually link elements of your HTML pages together, using what we call Connections.  A Connection appears as a line of some description - the path that the line follows depends on what type of Connection you use.  jsPlumb ships with two Connections - a straight line, and a Bezier curve - but Connections are pluggable and it is relatively easy to create your own.

Each Connection is established between two Endpoints.  An Endpoint is the point on some element at which the Connection joins, and it has some visual representation of its own.  You can see various different types of Endpoints on the demonstration pages.  jsPlumb ships with three different types of Endpoints: a Dot, a Rectangle, and an Image, but as with Connections, Endpoint implementations are pluggable.

Each Endpoint is associated with an Anchor.  Anchors define where on an element an Endpoint should be located.  Anchors do not have any visual representation of their own; they are simply used for positioning.  jsPlumb ships with several default Anchors - TopLeft, TopCenter, TopRight, RightMiddle, BottomRight, BottomCenter, BottomLeft, LeftMiddle and Center.  Hopefully their names are self explanatory.  Once again, it is easy to create your own Anchor implementation and plug it in to jsPlumb, but there is also a helper method that should cover most of your needs (see the last example in this post).

Under the hood, jsPlumb uses the Canvas element to draw Connections and Endpoints.  This is supported in most browsers but not IE; fortunately, though, Google created ExplorerCanvas.js, which simulates the Canvas element in IE.

So now we’ve got those few concepts out there, let’s take a look at a simple connection:

jsPlumb.connect({source:'element1', target:'element2'});

This is the most basic connection you can make in jsPlumb - all you have to provide is the ID of the two elements to connect.  Everything that you can specify yourself in jsPlumb also has a default setting, so in this case jsPlumb will use defaults for all of these things:

• the type of Connection (Bezier curve is the default)
• the parameters for the Bezier curve (how curvy it should be)
• the appearance of the Bezier curve - color, gradient, line width, etc
• the type of Endpoint (Dot is the default)
• the radius of the Endpoint (because it’s using Dot.  Other Endpoint types have different default values)
• the appearance of the Endpoint - color, gradient, etc
• the Anchor that the Endpoint uses (TopMiddle is the default)

So let’s look at providing values for some of those defaults.  In this next example, we’re going to tell jsPlumb that the Connection should be black and 10 pixels wide, the Endpoints should be rectangles of size 10x15, and the connection should go from the RightMiddle of one element to the BottomLeft of the other:

jsPlumb.connect( { 
   source:'element1',
   target:'element2', 
   paintStyle:{ lineWidth:10, strokeStyle:'black' }, 
   endpoint:new jsPlumb.Endpoints.Rectangle({width:10, height:15}), 
   anchors:["RightMiddle", "BottomLeft"]

});

There are a few things to note about this:

• The entries in the paintStyle object may be anything that is valid as a parameter to the context of a Canvas element. jsPlumb simply passes these values through.
• the ‘endpoint’ entry shows you how to create a Rectangle Endpoint. Note that you have to use “new jsPlumb.Endpoints….”; that is the Endpoint class is not static. Each different type of Endpoint takes different arguments in its constructor.  Note here that since we supplied only one Endpoint, it will be used for both ends of the Connection.  The example below shows how to provide a different Endpoint for each end.
• Anchors should be referred to by name, eg ‘“RightMiddle” or “BottomLeft”. They are NOT static and cannot be shared amongst connections.

The last example I’ll give you today will expand on the previous one a little.  Here we’re going to specify different Endpoints for each end of the Connection, each with its own paint style, and we’ll also specify a gradient for the Connection:

jsPlumb.connect( { 
   source:'element1',
   target:'element2', 
   paintStyle:{
      lineWidth:10,
      gradient:{ stops:[[0, 'blue'],[1, 'red']] }
   }, 
   endpoints:[ new jsPlumb.Endpoints.Dot({radius:10}), new jsPlumb.Endpoints.Dot({radius:25}) ],
   endpointStyles:[{fillStyle:'blue'}, {fillStyle:'red'}],
   anchors:[[0.333, 1, 0, 1], [0.333, 0, 0,-1] ]
});

• Gradients are specified using an array containing [location,value] pairs. Each location indicates a fraction of the length of the Connection; these values must be between 0 and 1 inclusive.
• Gradients do not work in IE - jsPlumb uses ExplorerCanvas for IE support, and ExplorerCanvas does not support gradients.  You will have to wait for IE9!
• The Anchors in this example specify custom locations.  The four elements in the array are [x, y, xOrientation, yOrientation]. ‘x’ and ‘y’ are fractions that specify where in each direction the Anchor should be located (relative to the origin) - in this case the first Anchor is located at a point one third of the width of the element, and the full height (ie. the bottom), and the second is located at one third of the width and y=0, ie. the top.  xOrientation and yOrientation tell jsPlumb which direction a Connection from that Anchor should go in.  For the first Anchor the values are [0, 1], meaning go straight down.  The second has [0, -1] - go straight up.  

The jsPlumb documentation can be found here: 

http://jsPlumb.org/doc/usage.html