Overlays are UI elements that are painted onto Connections, such as Labels or Arrows.
jsPlumb comes with five types of Overlays:
PlainArrow and Diamond are actually just configured instances of the generic Arrow overlay (see examples).
A key concept with Overlays is that of their location.
For a Connector, the location of an Overlay refers to some point along the path inscribed by the Connector. It can be specified in one of three ways:
For an Endpoint, the same principles apply, but location is specified as an [x,y] array. For instance, this would specify an Overlay that was positioned in the center of an Endpoint:
location:[ 0.5, 0.5 ]
Whereas this would specify an Overlay that was positioned 5 pixels along the x axis from the top left corner:
location: [ 5, 0 ]
And this would specify an Overlay that was positioned 5 pixels along the x axis from the bottom right corner:
location: [ -5, 0 ]
All Overlays support these two methods for getting/setting their location:
You can specify one or more overlays when making a call to jsPlumb.connect, jsPlumb.addEndpoint or jsPlumb.makeSource (but not jsPlumb.makeTarget: overlays are always derived from what the source of a Connection defines) The three cases are discussed below:
In this example we'll create an Arrow with the default options for an Arrow, and a label with the text "foo":
jsPlumb.connect({
...
overlays:[
"Arrow",
[ "Label", { label:"foo", location:0.25, id:"myLabel" } ]
],
...
});
This connection will have an arrow located halfway along it, and the label "foo" one quarter of the way along. Notice the id parameter; it can be used later if you wish to remove the Overlay or change its visibility (see below).
Another example, this time with an absolute location of 50 pixels from the source:
jsPlumb.connect({
...
overlays:[
"Arrow",
[ "Label", { label:"foo", location:50, id:"myLabel" } ]
],
...
});
Note in this example that we use the parameter connectorOverlays and not overlays as in the last example. This is because overlays would refer to Endpoint Overlays:
jsPlumb.addEndpoint("someDiv", {
...
overlays:[
[ "Label", { label:"foo", id:"label", location:[-0.5, -0.5] } ]
],
connectorOverlays:[
[ "Arrow", { width:10, length:30, location:1, id:"arrow" } ],
[ "Label", { label:"foo", id:"label" } ]
],
...
});
This connection will have a 10x30 Arrow located right at the head of the connection, and the label "foo" located at the halfway point. The Endpoint itself also has an overlay, located at [ -0.5 * width, -0.5 * height ] relative to the Endpoint's top,left corner.
Note in this example that we again use the parameter connectorOverlays and not overlays. The endpoint parameter to jsPlumb.makeSource supports everything you might pass to the second argument of a jsPlumb.addEndpoint call:
jsPlumb.makeSource("someDiv", {
...
endpoint:{
connectorOverlays:[
[ "Arrow", { width:10, length:30, location:1, id:"arrow" } ],
[ "Label", { label:"foo", id:"label" } ]
]
}
...
});
This connection will have a 10x30 Arrow located right at the head of the connection, and the label "foo" located at the halfway point.
addOverlay method on an Endpoint or ConnectionEndpoints and Connections both have an addOverlay method that takes as an argument a single Overlay definition. An example:
var e = jsPlumb.addEndpoint("someElement");
e.addOverlay([ "Arrow", { width:10, height:10, id:"arrow" }]);
Draws an arrow, using four points: the head and two tail points, and a foldback point, which permits the tail of the arrow to be indented. Available constructor arguments for this Overlay are:
This is just a specialized instance of Arrow in which jsPlumb hardcodes foldback to 1, meaning the tail of the Arrow is a flat edge. All of the constructor parameters from Arrow apply for PlainArrow.
This is a specialized instance of Arrow in which jsPlumb hardcodes 'foldback' to 2, meaning the Arrow turns into a Diamond. All of the constructor parameters from Arrow apply for Diamond.
Provides a text label to decorate Connectors with. The available constructor arguments are:
labelStyle parameter.The Label overlay offers two methods - getLabel and setLabel - for accessing/manipulating its content dynamically:
var c = jsPlumb.connect({
source:"d1",
target:"d2",
overlays:[
[ "Label", {label:"FOO", id:"label"}]
]
});
...
var label = c.getOverlay("label");
console.log("Label is currently", label.getLabel());
label.setLabel("BAR");
console.log("Label is now", label.getLabel());
In this example you can see that the Label Overlay is assigned an id of "label" in the connect call, and then retrieved using that id in the call to Connection's getOverlay method.
Both Connections and Endpoints support Label Overlays, and because changing labels is quite a common operation, setLabel and getLabel methods have been added to these objects:
var conn = jsPlumb.connect({
source:"d1",
target:"d2",
label:"FOO"
});
...
console.log("Label is currently", conn.getLabel());
conn.setLabel("BAR");
console.log("Label is now", conn.getLabel());
These methods support passing in a Function instead of a String, and jsPlumb will create a label overlay for you if one does not yet exist when you call setLabel:
var conn = jsPlumb.connect({
source:"d1",
target:"d2"
});
...
conn.setLabel(function(c) {
var s = new Date();
return s.getTime() + "milliseconds have elapsed since 01/01/1970";
});
console.log("Label is now", conn.getLabel());
The Custom Overlay allows you to create your own Overlays, which jsPlumb will position for you. You need to implement one method - create(component) - which is passed the component on which the Overlay is located as an argument, and which returns either a DOM element or a valid selector from the underlying library:
var conn = jsPlumb.connect({
source:"d1",
target:"d2",
paintStyle:{
strokeStyle:"red",
lineWidth:3
},
overlays:[
["Custom", {
create:function(component) {
return $("<select id='myDropDown'><option value='foo'>foo</option><option value='bar'>bar</option></select>");
},
location:0.7,
id:"customOverlay"
}]
]
});
Here we have created a select box with a couple of values, assigned to it the id of 'customOverlay' and placed it at location 0.7. Note that the 'id' we assigned is distinct from the element's id. You can use the id you provided to later retrieve this Overlay using the getOverlay(id) method on a Connection or an Endpoint.
You can control the visibility of Overlays using the setVisible method of Overlays themselves, or with showOverlay(id) or hideOverlay(id) on a Connection.
Remember the id parameter that we specified in the examples above? This can be used to retrieve the Overlay from a Connection:
var connection = jsPlumb.connect({
...
overlays:[
"Arrow",
[ "Label", { label:"foo", location:0.25, id:"myLabel" } ]
],
...
});
// time passes
var overlay = connection.getOverlay("myLabel");
// now you can hide this Overlay:
overlay.setVisible(false);
// there are also hide/show methods:
overlay.show();
overlay.hide();
However, Connection and Endpoint also have two convenience methods you could use instead:
var connection = jsPlumb.connect({
...
overlays:[
"Arrow",
[ "Label", { label:"foo", location:-30 }, id:"myLabel" ]
],
...
});
// time passes
connection.hideOverlay("myLabel");
// more time passes
connection.showOverlay("myLabel");
Connection and Endpoint also have a removeOverlay method, that does what you might expect:
var connection = jsPlumb.connect({
...
overlays:[
"Arrow",
[ "Label", { label:"foo", location:0.25 }, id:"myLabel" ]
],
...
});
// time passes
connection.removeOverlay("myLabel");