view demo | contact me

Index

This document refers to release 1.0.4 of jsPlumb. 05/17/10

Summary

 jsPlumb allows you to connect elements on the screen with "plumbing", using a Canvas element when supported, and Google's ExplorerCanvas script to support older browsers.

It's written as a jQuery plugin, and relies on jQuery 1.3.x or jQuery 1.4.x (tested on 1.3.2 and 1.4.2), and also jQuery UI 1.7.2 or 1.8.0 (if you want to support dragging). For Canvas support in IE you also need to include Google's ExplorerCanvas script.

jsPlumb has been tested on the following browsers:

Basic configuration

 To use jsPlumb you need jQuery 1.3.x or 1.4.x, jQueryUI 1.7.x or 1.8.x, and ExplorerCanvas: 
<script type="text/javascript" src="http://explorercanvas.googlecode.com/svn/trunk/excanvas.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.7.2/jquery-ui.min.js"></script>
<script type="text/javascript" src="PATH_TO/jquery.jsPlumb-1.0.4-min.js "></script>

Unloading jsPlumb

 jsPlumb offers a method you can call when your page is unloading. You should do this to insure against memory leaks. You configure it like this: 
<body onunload="jsPlumb.unload();">

...

</body>

Upcoming in version 1.1.0

Changes between 1.0.3 AND 1.0.4

Examples

 The basic syntax of a call is that you execute 'plumb' on some element, providing a target, and optionally a paintStyle and preferences for where you want the plumbing to be anchored on each element, as well as the type of connector to use:

Automatic Repaint

 jsPlumb attaches a listener to the browser window and automatically repaints every connection when a window resize event occurs. You can disable this functionality, if you want to, with the following call: 
jsPlumb.setAutomaticRepaint(false);
You can also provide your own function for jsPlumb to execute instead of its default behaviour: 
var repaint = function() {	
	// do some things, perhaps, and then...
	jsPlumb.repaintEverything();
};

jsPlumb.setRepaintFunction(repaint);
Notice the call to repaintEverything() here - a useful method.

Another example"

var repaint = function() {	
	// completely start over	
	jsPlumb.detachEverything();
	// paint all your connections
};

jsPlumb.setRepaintFunction(repaint);

Options

These are the options you can specify on a call to the plumb method:

Defaults

 The easiest way to set a look and feel for your plumbing is to override the defaults that jsPlumb uses. If you do not do this you are forced to provide your overridden values on every call. Every argument to the plumb method has an associated default value in jsPlumb.

The defaults that ship with jsPlumb are: 
DEFAULT_PAINT_STYLE : {
    lineWidth : 10,
    strokeStyle : "red"
}
			
DEFAULT_DRAG_OPTIONS : { }

DEFAULT_ENDPOINT_STYLE : { fillStyle : null; }

DEFAULT_ENDPOINT_STYLES : [ null, null ]

DEFAULT_ANCHORS : [ jsPlumb.Anchors.BottomCenter, jsPlumb.Anchors.TopCenter ]

DEFAULT_CONNECTOR : jsPlumb.Connectors.Bezier;

DEFAULT_ENDPOINT : jsPlumb.Endpoints.Dot;

DEFAULT_ENDPOINTS : [jsPlumb.Endpoints.Dot, jsPlumb.Endpoints.Dot];

Note that in DEFAULT_ENDPOINT_STYLE, the default fillStyle is 'null'. This instructs jsPlumb to use the strokeStyle from the attached connector to fill the endpoint.

Note also that you can specify either or both (or neither) of 'DEFAULT_ENDPOINT_STYLE' and 'DEFAULT_ENDPOINT_STYLES'. This allows you to specify a different end point for each end of a connection. 'DEFAULT_ENDPOINT' and 'DEFAULT_ENDPOINTS' use the same concept. jsPlumb will look first in the individual endpoint/endpoint style arrays, and then fall back to the single default version.

you can override these defaults by including this in a script somewhere: 
jsPlumb.DEFAULT_PAINT_STYLE = {
	lineWidth:13,
	strokeStyle: 'rgba(200,0,0,100)'
}

jsPlumb.Defaults.DragOptions = { cursor: 'crosshair' };

jsPlumb.DEFAULT_ENDPOINTS = [ new jsPlumb.Endpoints.Dot(7), new jsPlumb.Endpoints.Dot(11) ]

jsPlumb.DEFAULT_ENDPOINT_STYLES = [{ fillStyle:'#225588' }, { fillStyle:'#558822' }];
after the jsPlumb script has been loaded of course! Here we have specified the following default behaviour:

Anchors

An Anchor models the notion of where on an element a plumb line should connect. jsPlumb has nine default anchor locations you can use to specify where the plumb lines connect to elements: these are the four corners of an element, the center of the element, and the midpoint of each edge of the element.

You can provide your own anchor locations if you need to. jsPlumb supports two ways of doing this:

Connectors

 Connectors are the lines that actually join elements of the UI. jsPlumb has two connector implementations - a straight line and a Bezier curve. The default connector is the Bezier curve.

jsPlumb attaches the CSS class _jsPlumb_connector to Connectors that it generates.

Bezier Connector

The Bezier Connector provides a Bezier path between the two endpoints. You construct one like this:

var myConnector = new jsPlumb.Connectors.Bezier(curviness);

curviness, which is optional (and defaults to 150), defines the distance in pixels that the Bezier's control points are situated from the anchor points. This does not mean that your connector will pass through a point at this distance from your curve. It is a hint to how you want the curve to travel. Rather than discuss Bezier curves at length here, because they are a very complex topic, we refer you to Wikipedia.

Straight Connector

The Straight Connector draws a straight line between the two endpoints. You construct one like this:

var myConnector = new jsPlumb.Connectors.Straight();

Custom Connectors

You can provide your own connectors if you need to. A Connector consists of two functions, which work as a pair. First a call is made to the compute function: 
this.compute = function(sourcePos, targetPos, sourceAnchor, targetAnchor, lineWidth) { 
	... 
	return dimensions;	
}
which is expected to return a list that the paint function can make sense of. The first four entries in the list must be the [x,y,width,height] values for the canvas that the connector will be drawn on; jsPlumb will use this information to size the canvas prior to calling the Connector's paint function. Therefore it is the Connector's responsibility to ensure that the returned dimensions describe a large enough space for the line that will be drawn on it.

The next four elements must be the coordinates of the two endpoints of the line you are going to draw.

The remainder of the items in the returned list are arbitrary, and will vary between Connector implementations; this list is passed in to a Connector's paint function, so each implementation will put into the list whatever it needs to paint itself. For instance, the straight line connector only needs the [x,y] location of each end of the line it will paint, and that is one of the required entries, so it does not have to do anything extra, whereas the Bezier connector adds the location of the two control points. Other types of Connectors will do whatever is appropriate for their particular situation.

This is the method signature for the paint function: 
this.paint = function(dimensions, ctx) { .. }
here, the 'dimensions' argument to the 'paint' function is the return value of the 'compute' function. The 'ctx' argument is the Canvas context; you will do all your drawing on this.

To change the connector from the default, specify it in your plumb call: 
$("#someWindow").plumb({target:'otherWindow', connector:new jsPlumb.Connectors.Straight()});

Endpoints

An Endpoint is the UI component that marks the location of an Anchor, ie. the place where a Connector joins an element. jsPlumb comes with four Endpoint implementations - Blank, Dot, Rectangle and Image.

To create your own Endpoint implementation, you need to implement a single method: 

paint : function(anchorPoint, orientation, canvas, endpointStyle, connectorPaintStyle) { ... }
The arguments to this method are as follows:

It is your responsibility to size and locate the canvas to suit your needs. jsPlumb provides the following helper method to assist you: 

jsPlumb.sizeCanvas(canvas, x, y, width, height);
Allows you to locate the canvas on screen and to size it.

Gradients

 The Canvas element supports gradients, and jsPlumb can take advantage of this when painting your Connectors and/or Endpoints. Note: this does NOT WORK in IE, because we use ExplorerCanvas in IE and ExplorerCanvas does not support gradients.

There are two types of gradients available in Canvas - a 'linear' gradient, which consists of colored lines all going in one direction, and a 'radial' gradient, which consists of colored circles emanating from one circle to another. Because of their basic shape, jsPlumb supports only linear gradients for Connectors. But for Endpoints, jsPlumb supports both linear and radial gradients.

Connector gradients

To specify a linear gradient to use in a Connector, you must add a gradient object to your Connector's paintStyle, for instance: 
$("#window2").plumb({
	target:'window3', 
	paintStyle:{ 
		gradient:{
			stops:[[0,'green'], [1,'red']]
		}, 
		lineWidth:15 
	}
});
Here we have plumbed window2 to window3 with a 15 pixel wide connector that has a gradient from green to red.

Notice the gradient object and the stops list inside it - the gradient consists of an arbitrary number of these "color stops". Each color stop is comprised of two values - [position, color]. Position must be a decimal value between 0 and 1 (inclusive), and indicates where the color stop is situated as a fraction of the length of the entire gradient. Valid values for the colors in the stops list are the same as those that are valid for strokeStyle when describing a color.

As mentioned, the stops list can hold an arbitrary number of entries. Here's an example of a gradient that goes from red to blue to green, and back again through blue to red: 

$("#window2").plumb({
	target : 'window3', 
	paintStyle : { 
		gradient:{ 
			stops:[[0,'red'], [0.33,'blue'], [0.66,'green'], [0.33,'blue'], [1,'red']]
		}, 
		lineWidth : 15 
	}
});
Note: jsPlumb uses ExplorerCanvas for IE, which does not support gradients. On IE, jsPlumb will simply ignore the gradient directive so it is best to ensure you also supply a strokeStyle in your paintStyle object, to give jsPlumb something to fall back on. If you do not supply a strokeStyle your Connectors will be painted black. The previous example might look like this, for instance: 
$("#window2").plumb({
	target:'window3', 
	paintStyle:{ 
		strokeStyle:'red', 
		gradient:{
			stops:[[0,'red'], [0.33,'blue'], [0.66,'green'], [0.33,'blue'], [1,'red']]
		}, 
		lineWidth:15 
	}
});
Notice the strokeStyle:'red' directive at the beginning of the parameter list in paintStyle.

Endpoint gradients

Endpoint gradients are specified using the same syntax as Connector gradients. You put the gradient specifier either in the endpoint member, or if you are specifying different Endpoints for each end of the Connector, in one or both of the values in the endpoints array.

This is an example of an Endpoint gradient that is different for each Endpoint in the Connector. This comes from the main demo; it is the Connector joining Window 2 to Window 3: 

var w23Stroke = 'rgb(189,11,11)'; 
$("#window2").plumb({
	target:'window3', 
	paintStyle:{
		lineWidth:8,
		strokeStyle:w23Stroke
	}, 
 	anchors:[ jsPlumb.makeAnchor(0.3,1,0,1), jsPlumb.Anchors.TopCenter ], 
 	endpoint:new jsPlumb.Endpoints.Rectangle(), 
 	endpointStyles:[
 		{ gradient : {stops:[[0, w23Stroke], [1, '#558822']] } },
    	{ gradient : {stops:[[0, w23Stroke], [1, '#882255']] } }
    ]
});
The first entry in the gradient will be the one that is on the Connector end of the Endpoint. You can of course have as many color stops as you want in this gradient, just like with Connector gradients.
Applying the gradient in Endpoints
Only the Dot and Rectangle endpoints honour the presence of a gradient (and, remember, not in IE). The Image endpoint of course ignores a gradient as it does no painting of its own.

The type of gradient you will see depends on the Endpoint type:

CSS Class Reference

 jsPlumb attaches classes to each of the UI components it creates:
componentcss class
connector_jsPlumb_connector
endpoint_jsPlumb_endpoint

Possible Future Enhancements