The shape of a link is determined by five properties - source
, target
, vertices
, connector
and router
.
The source
and target
properties have to be provided when creating a Link. Either an Element can be provided (either directly or via an id
property) or a Point (with x
and y
properties).
link.source(rect);
link.source({ id: rect.id });
link.source(new g.Point(100, 100));
link.source({ x: 100, y: 100 });
If the end is specified as an Element, a specific subelement on that element may be identified for use as the link end. The selector
property allows specifying the subelement with a selector string, while the magnet
property uses magnet id, and the port
property uses the port id.
For the purposes of link geometry, however, the most important are the anchor
and connectionPoint
properties of link end elements. The connectionStrategy
paper option is also relevant to mention in this context.
If the link end (source/target) is specified as an Element (whether or not one of the subelement specifications is in effect), the precise position of the link end's anchor may be specified by the anchor
property. (If the link end is specified as a Point, its coordinates are used as its anchor directly.) Every link has two anchors; one at the source end and one at the target end.
A link end anchor is a point inside a given (sub)element that the link path wants to connect to at that source/target end - if it were not obstructed by the body of the element itself (it is the role of connectionPoints to take the end element into account). Alongside link vertices, source and target anchors determine the basic link path. Then, it is the job of connectionPoints, routers, and connectors to modify that path to make it look good.
The anchor functions reference the end element to find the anchor point - e.g. the center of the end element, or its top-right corner. Notably, anchor functions also allow you to offset found anchor points by a custom distance in both dimensions from the standard position (e.g. 10 pixels to the right and 20 pixels below the center of an end element). Several pre-made anchors are provided inside the JointJS library in the joint.anchors
namespace.
link.source(rect, {
anchor: {
name: 'bottomLeft',
args: {
dx: 20,
dy: -10
}
}
});
If an anchor function is not provided, the defaultAnchor
paper option is used instead. The joint.anchors.center
function is used by default.
The link end's connection point may be specified by the connectionPoint
property. Every link has two connection points; one at the source end and one at the target end.
A link connection point is the point the the link path actually ends at, taking the end element into account. This point will always lie on the link path (the line connecting link anchors and vertices together, in order).
The connectionPoints are found by considering intersections between the link path and a desired feature of the end element (e.g. bounding box, shape boundary, anchor). Although connectionPoints are not capable of being offset off the link path (anchors should be used to modify the link path if this is required), they can be offset along the path - e.g. to form a gap between the element and the actual link. Several pre-made connectionPoints are provided in the JointJS library in the joint.connectionPoints
namespace.
link.source(rect, {
connectionPoint: {
name: 'boundary',
args: {
offset: 5
}
}
});
If a connection point function is not provided, the defaultConnectionPoint
paper option is used instead. The joint.connectionPoints.bbox
function is used by default.
Related to anchors and connectionPoints is the connectionStrategy
paper option. It allows you to specify which anchor
and connectionPoint
properties should be assigned to end elements in response to user interaction (e.g. in response to dragging a link arrowhead onto a new element). This setting is necessary because assigned anchor
and connectionPoint
are not preserved when the end element is reassigned by the user - and the paper's defaultAnchor
and defaultConnectionPoint
are used instead.
Several pre-made connectionStrategies are provided inside the JointJS library in the joint.connectionStrategies
namespace, but you may find it necessary to create your own custom connection strategies. This is a paper-level setting; connectionStrategies not assigned on a link-by-link basis.
paper.options.connectionStrategy = joint.connectionStrategies.pinAbsolute;
If a connection strategy is not provided, the joint.connectionStrategies.useDefaults
function is used by default.
The vertices
array is an array of user-defined points for the link to pass through. Alongside the source and target anchors, the link vertices determine the basic link path. This skeleton path is then used for determining the link route. The vertices can be accessed with the link.vertices()
function and related functions.
link.vertices();
link.vertices([{ x: 100, y: 120 }, { x: 150, y: 60 }]);
Routers take an array of link vertices and transform them into an array of route points that the link should go through. This route is then used for generating the connection SVG path commands. The router
property of a link can be accessed with the link.router()
function.
A collection of pre-made routers is provided inside the JointJS library in the joint.routers
namespace. This includes smart routers
that are able to automatically avoid obstacles (elements) in their way.
link.router('manhattan', {
excludeEnds: ['source'],
excludeTypes: ['myNamespace.MyCommentElement'],
startDirections: ['top'],
endDirections: ['bottom']
});
If a router is not provided, the defaultRouter
paper option is used instead. The joint.routers.normal
function is used by default.
Connectors take an array of link route points and generate SVG path commands so that the link can be rendered. The connector
property of a link can be accessed with the link.connector()
function.
A collection of pre-made connectors is provided inside the JointJS library in the joint.connectors
namespace.
link.connector('rounded', {
raw: true,
radius: 20
});
If a connector is not provided, the defaultConnector
paper option is used instead. The joint.connectors.normal
function is used by default.
Note that the modular architecture of JointJS allows mixing-and-matching connectors with routers as desired; for example, a link may be specified to use the jumpover
connector on top of the manhattan
router:
var link = new joint.shapes.standard.Link();
link.source(rect);
link.target(rect2);
link.router('manhattan');
link.connector('jumpover');
Styling of the link is contained in the attrs
property which has exactly the same structure as the attrs
property of elements. Please refer to the joint.dia.Element and joint.dia.Link sections of this page for more information.
Links also have the z
property which specifies the z-level of the link. It has exactly the same meaning as the z
property of elements.