The basic model for diagram links. It inherits from joint.dia.Cell with a few additional properties and methods specific to links. For a quick introduction to elements, see our tutorial.
Links' properties may be split into several groups according to their function:
Links have two crucial attributes: source
and target
. They define the starting point and the end point of the link. They can be defined with a Cell id (optionally, with additional subelement/magnet/port reference) or with a Point:
var link1 = new joint.dia.Link({
source: { id: sourceId },
target: { id: targetId, port: portId }
});
var link2 = new joint.dia.Link({
source: { id: sourceId },
target: { x: 100, y: 100 }
});
The source
and target
properties accept additional modifier properties that modify the actual position of the link end: anchor
/linkAnchor
, and connectionPoint
.
Additionally, the path of the link is determined by its vertices
, and the applied router
and connector
. All these attributes are described in more detail in link geometry documentation.
Each joint.dia.Link
defines its own SVG markup
which is then used by joint.dia.LinkView
to render the link to the paper. For instance, the joint.shapes.standard.Link
(which inherits from joint.dia.Link
) defines its markup using the JSON array notation as follows:
markup: [{
tagName: 'path',
selector: 'wrapper',
attributes: {
'fill': 'none',
'cursor': 'pointer',
'stroke': 'transparent',
'stroke-linecap': 'round'
}
}, {
tagName: 'path',
selector: 'line',
attributes: {
'fill': 'none',
'pointer-events': 'none'
}
}]
As we can see, the joint.shapes.standard.Link
shape consists of two subelements
: one SVGPathElement named 'wrapper'
and one SVGPathElement named 'line'
. The attrs
object refers to the subelements' names (selectors
) to provide SVG attributes to these constituent SVGElements.
The markup
attribute is not the only presentation attribute that may be specified for a joint.dia.Link
. However, all the following Link properties are deprecated and included only for backwards compatibility. Use link tools instead:
vertexMarkup
- provide default vertex markup for all vertices created on an instance of this Link type (on hover).toolMarkup
- provide custom tool markup for all instances of this Link type (on hover).doubleToolMarkup
- provide custom markup for second set of tools for all instances of this Link type (on hover, if linkView.doubleLinkTools
is true
).arrowheadMarkup
- provide custom arrowhead markup for all instances of this Link type (on hover).The keys of the attrs
object are selectors that match subelements defined in the link's markup
. The values of this object are SVG attributes that will be set on the selected subelements. One can find the full list of SVG attributes and their descriptions online, e.g. on MDN.
For example, in order to set a red stroke color on a subelement called 'line'
, the attrs
object would contain:
line: { stroke: 'red' }
If you simply need to change a value of an attribute, it is not recommended to modify the attrs
object directly. Instead, use the link.attr()
method.
We can use the joint.shapes.standard.Link
(which inherits from joint.dia.Link
) as an example. The attrs
object in its definition is provided below:
attrs: {
line: {
connection: true,
stroke: '#333333',
strokeWidth: 2,
strokeLinejoin: 'round',
targetMarker: {
'type': 'path',
'd': 'M 10 -5 0 0 10 5 z'
}
},
wrapper: {
connection: true,
strokeWidth: 10,
strokeLinejoin: 'round'
}
}
Notice that the object makes use of special JointJS attributes (e.g. connection
, targetMarker
) on top of standard SVG attributes (e.g. stroke
, strokeWidth
). All of these special attributes
are listed in the attributes section of this documentation. You should also refer to our tutorial on special attributes.
In the context of links, the most important special attribute is connection
. It specifies that the SVGPathElement(s) in question should follow the path of the Link's model, as provided by the interplay of link geometry methods.
The z
property specifies the stack order of the element in the SVG DOM. An element with a higher z
value will be rendered in front of an element with a lower z
value. (This also applies to Elements.)
You may provide an array of labels to the link through the labels
attribute. Each can have its own markup, position, and attrs. See the link labels documentation. You should also refer to our tutorial on link labels.
It is also possible to pass custom attributes to the link. These may be useful to identify an individual link model for the purposes of linkView interaction (see LinkView
documentation for more information). For example, to only enable custom contextmenu interaction for link1
but not link2
:
var CustomLinkView = joint.dia.LinkView.extend({
contextmenu: function(evt, x, y) {
if (this.model.get('customLinkInteractions')) {
// only links with `customLinkInteractions: true`
this.addLabel(x, y);
}
}
});
var paper = new joint.dia.Paper({
//...
linkView: CustomLinkView,
interactive: function(cellView) {
if (cellView.model.get('customLinkInteractions')) {
// only links with `customLinkInteractions: true`
return { vertexAdd: false };
}
return true; // otherwise
}
});
var link1 = new joint.dia.Link({
//...
customLinkInteractions: true // right-click adds a label
});
var link2 = new joint.dia.Link({
//...
customLinkInteractions: false // or omit completely
});
Links trigger several special events, detailed in the link events documentation.
It is possible to extend the joint.dia.Link
class to create a custom link. A custom link may override Link properties to assign its own defaults. These values override builtin defaults, if provided, and are applied to all instances of the new Link type, unless an individual instance overrides them with its own values. The following Link properties are applicable in this context:
markup
- provide default link markup for all instances of this Link type, specified with a JSON array.attrs
- provide default link attributes for all instances of this Link type. These allow you to change the style and size of SVG elements, identified by their selectors.defaultLabel
- provide default properties (markup, attrs, position) for all labels created on an instance of this Link type.The values of these defaults may be important; the linkView.addLabel()
shortcut function is only capable of adding default labels to the link.
Creating custom links is explained in more detail in our tutorial.
Example:
var CustomLink = joint.dia.Link.define('examples.CustomLink', {
defaultLabel: {
markup: [
{
tagName: 'circle',
selector: 'body'
}, {
tagName: 'text',
selector: 'label'
}
],
attrs: {
label: {
text: '%', // default label text
fill: '#ff0000', // default text color
fontSize: 14,
textAnchor: 'middle',
yAlignment: 'middle',
pointerEvents: 'none'
},
body: {
ref: 'label',
fill: '#ffffff',
stroke: '#000000',
strokeWidth: 1,
refR: 1,
refCx: 0,
refCy: 0
}
},
position: {
distance: 0.5, // place label at midpoint by default
offset: {
y: -20 // offset label by 20px upwards by default
},
args: {
absoluteOffset: true // keep offset absolute when moving by default
}
}
}
});
var link = new CustomLink({
//...
});
To ensure backwards compatibility, the joint.dia.Link
class comes with a private builtin defaultLabel
attribute. It is reproduced here for reference:
defaultLabel: {
// builtin default markup:
// used if neither defaultLabel.markup
// nor label.markup is set
markup: [
{
tagName: 'rect',
selector: 'rect'
}, {
tagName: 'text',
selector: 'text'
}
],
// builtin default attributes:
// applied only if builtin default markup is used
attrs: {
text: {
fill: '#000000',
fontSize: 14,
textAnchor: 'middle',
yAlignment: 'middle',
pointerEvents: 'none'
},
rect: {
ref: 'text',
fill: '#ffffff',
rx: 3,
ry: 3,
refWidth: 1,
refHeight: 1,
refX: 0,
refY: 0
}
},
// builtin default position:
// used if neither defaultLabel.position
// nor label.position is set
position: {
distance: 0.5
}
}
If custom position
object is not provided (neither as a type default nor as an instance value), builtin default label position is applied instead ({ distance: 0.5 }
).
Furthermore, if custom markup
is not provided (neither as a type default nor as an instance value), builtin default label markup is applied, alongside the builtin default label attrs object. However, it is very highly recommended that you provide both your own markup
and your own attrs
- unless you want to use the builtin default precisely as-is.