This is the fifth article of the intermediate section of the JointJS tutorial. Go back to custom elements. Alternatively, you can return to index of all articles.
JointJS comes with several built-in link shapes; we have already encountered
joint.shapes.standard.Link in the basic links tutorial.
However, builtin link definitions are not as plentiful as element definitions. It is thus very possible that you will find the need to define your own custom link type. Creating custom links is very similar to creating custom elements, with a few differences. The Link class is discussed in JointJS documentation, as well.
A new Link subtype is registered by calling the define() function:
Link.define(type [, defaultInstanceProperties, prototypeProperties, staticProperties])
- define a new subtype of this Link class.If you want to create a Link subtype from scratch, you should inherit from the default
joint.dia.Link class by calling joint.dia.Link.define().
You can also inherit from any predefined link (e.g. joint.shapes.standard.Link.define())
and even any custom link subtype you have previously defined.
Here is how the parameters of the define() function map to familiar building blocks of
links:
type - the name of the subtype class.defaultInstanceProperties - object that contains properties to be assigned to every
constructed instance of the subtype.
Used for specifying default attributes.prototypeProperties - object that contains properties to be assigned on the subtype
prototype.
Intended for properties intrinsic to the subtype, not usually modified.
Used for specifying shape markup.staticProperties - object that contains properties to be assigned on the subtype
constructor.
Not very common, used mostly for alternative constructor
functions.Let us use the familiar
joint.shapes.standard.Link
shape definition as an example:
joint.dia.Link.define('standard.Link', {
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'
}
}
}, {
markup: [{
tagName: 'path',
selector: 'wrapper',
attributes: {
'fill': 'none',
'cursor': 'pointer',
'stroke': 'transparent'
}
}, {
tagName: 'path',
selector: 'line',
attributes: {
'fill': 'none',
'pointer-events': 'none'
}
}]
});The first argument of the define() function is a unique identifier under which you want to
be able to find the new type.
The first part of the name, joint.shapes, is implied.
Thus, we can see that the name of a type accessed as joint.shapes.standard.Link has to
be 'standard.Link'.
Markup is usually provided inside the third argument of the define() function (prototype
properties) for improved performance.
(This is because markup is something that all instances of the link type are expected to have in
common, so inheriting from subtype prototype is more efficient.
Nevertheless, it is still possible to provide custom markup to individual instances of your class by
providing individual markup later.)
The markup property is specified as a JSON array.
Each member of the array is taken to define one subelement of the new shape.
Subelements are defined with objects containing a tagName (a string with the SVG tag
name of the subelement) and a selector (a string identifier for this subelement
in the shape).
Although JointJS can also understand SVG markup in string form, that approach is noticeably slower due
to the need for parsing and lack of capacity for custom selectors.
A joint.shapes.standard.Link is composed of two subelements - an
SVGPathElement named line and an SVGPathElement named wrapper.
The line is the subelement that is supposed to be styled, while wrapper is a
transparent helper subelement underneath the line that is designed to be interacted
with.
{
markup: [{
tagName: 'path',
selector: 'wrapper',
attributes: {
'fill': 'none',
'cursor': 'pointer',
'stroke': 'transparent'
}
}, {
tagName: 'path',
selector: 'line',
attributes: {
'fill': 'none',
'pointer-events': 'none'
}
}]
}As you can see, attributes can also be defined inside markup.
These are intended for attributes that all instances of a link type are expected to have in common;
for such attributes, it is more efficient to inherit these attributes from the subtype prototype instead
of each instance having their own copy because it avoids unnecessary iterations in the cell attributes
update loop.
(Nevertheless, again, it is possible to overwrite these prototype attributes by individual instance
attributes if absolutely necessary.)
In our example, markup.attributes are used to reflect the intended use of the two
subelements of the link, which is not expected to change - wrapper has a transparent stroke
since it is not expected to be styled, while line has 'pointer-events'
deactivated since it is not expected to be interacted with.
Both subelement paths also remove the default SVGPathElement 'fill' which is not usually
terribly useful within links.
An important caveat is that markup.attributes can only store native SVG attributes,
not JointJS attrs.
This means that JointJS special attributes are not recognized (since markup.attributes are
supposed not to change, they would not be able to reflect possible changes in referenced subelements or in the
size/position of model bbox).
Additionally, this means that there is no JointJS kebab-case translation of attribute names; thus, using
quotes around all attribute names is encouraged in this context, to communicate these restrictions to
programmers (i.e. 'fill', not fill; 'pointer-events', not
pointerEvents).
Default attributes are usually provided inside the second argument of the define() function
(default instance properties).
(This is because all instances of the link type are expected to have their own individual attributes, so
inheriting from the prototype is likely to cause unnecessary overhead.)
In the attrs object, keys correspond to subelement selectors, as defined in the
markup.
For each subelement, an object with attribute name-value pairs is then expected.
Each of these attributes can be a native SVG attribute or a JointJS
special attribute.
In joint.shapes.standard.Link, we can see that the subelement referenced by
line (i.e. the stylable SVGPathElement component of the link) has a default dark-gray
stroke of width 2, and a default target marker that looks like a small arrow.
(Since the default target marker has no fill or stroke set, the colors are
inherited from the line.stroke attribute by default.)
The wrapper subelement (the interactive SVGPathElement component of the link) has a wider
transparent stroke to make the link easier to click for users.
Finally, notice that both subelements have the connection
special attribute set to
true.
This means that they both automatically follow the connection path of the link instance as calculated by
the link geometry functions:
{
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'
}
}
}The second argument of the define() function (default instance properties) is also where
defaultLabel for custom Link subtypes may be specified.
This allows you to provide custom default markup and attrs for labels that are created on an instance of
your custom Link type.
The joint.shapes.standard.Link
does not define its own custom default
label, so the
builtin default markup
and attributes are used unless they are overridden by individual label markup and
attrs.
The defaultLabel accepts three properties:
defaultLabel.markup - sets the default markup of labels created on this Link subtype.
Expected in the JSON markup format.defaultLabel.attrs - sets the default attributes of label subelements on this Link
subtype.
Uses selectors defined in markup.
See default.defaultLabel.position - sets the default position along the line at which labels will
be added for instances of this Link subtype.
Default is 0.5 (midpoint of the connection path).Link labels are explained in depth in a separate section of the intermediate tutorial.
Static properties are not used by joint.shapes.standard.Link, but let us discuss them a
little bit to gain a complete overview of custom links.
Similarly to our custom element example, imagine we
wanted to define our own subtype of joint.shapes.standard.Link (which we name
'examples.CustomLink'), with the added benefit of a constructor function that
chose a random style for the link's line - maybe because we need to add a lot of diverse links quickly.
We could do this with a static function createRandom; then, we would have two ways to
obtain an instance of CustomLink:
With the standard constructor ...
var customLink = new joint.shapes.examples.CustomLink();... or with the new static function:
var customLink = joint.shapes.examples.CustomLink.createRandom();Both of these functions are demonstrated in our example.
Let us apply everything we learned so far and create a new
joint.shapes.standard.Link.
Keep in mind that the provided instance properties are mixined with the parent definition, but prototype
and static properties are not.
This means that it is enough for us to record only the attributes that changed in the definition of the
custom element subtype (however, if we wanted to change the markup, we would have to do so
explicitly).
joint.shapes.standard.Link.define('examples.CustomLink', {
attrs: {
line: {
stroke: 'cornflowerblue',
strokeWidth: 5,
targetMarker: {
'type': 'rect',
'width': 10,
'height': 20,
'y': -10,
'stroke': 'none'
}
}
},
defaultLabel: {
markup: [
{
tagName: 'rect',
selector: 'body'
}, {
tagName: 'text',
selector: 'label'
}
],
attrs: {
label: {
fill: 'black', // default text color
fontSize: 12,
textAnchor: 'middle',
yAlignment: 'middle',
pointerEvents: 'none'
},
body: {
ref: 'label',
fill: 'white',
stroke: 'cornflowerblue',
strokeWidth: 2,
refWidth: '120%',
refHeight: '120%',
refX: '-10%',
refY: '-10%'
}
},
position: {
distance: 100, // default absolute position
args: {
absoluteDistance: true
}
}
}
}, {
// inherit joint.shapes.standard.Link.markup
}, {
createRandom: function() {
var link = new this();
var stroke = '#' + ('000000' + Math.floor(Math.random() * 16777215).toString(16)).slice(-6);
var strokeWidth = Math.floor(Math.random() * 10) + 1;
var strokeDasharray = (Math.floor(Math.random() * 5) + 1) + ' ' + (Math.floor(Math.random() * 5) + 1);
link.attr({
line: {
stroke: stroke,
strokeWidth: strokeWidth,
strokeDasharray: strokeDasharray
}
});
link.prop('defaultLabel/attrs/body/stroke', stroke);
return link;
}
});The following example shows the default look of joint.shapes.standard.Link (i.e. with no
instance attributes set) alongside the default look of our custom link and the randomized results of the
createRandom() constructor function.
Every link has a default label added as well.
Try refreshing the page to see
createRandom() in action.
JointJS source code: custom-links.js
In the next section of the intermediate tutorial, we will learn about link labels.