Joint API

This is the API reference to the open source JointJS core library. If you're looking for the Rappid diagramming toolkit documentation, you can find that here.

JointJS library exports three global variables: joint, V and g.

The joint namespace contains all the objects that you will use to build your diagrams. Additionally, joint.version property tells you which version of JointJS you're using.

The V global is lightweight SVG library that we call Vectorizer. This tiny library makes manipulation with SVG documents much easier. JointJS uses this library internally. Normally, you don't have to get in touch with this library at all but for advanced uses, it can be handy.

The g global is another lighweight library used internally by JointJS that provides many useful geometry operations. Again, you might not get in touch with this library but when you do have the need to perform geometric operations in your applications, you'll certainly find it helpful.

anchors

A link anchor is a point on the paper that the link wants to reach as its endpoint. (In reality, the end element will probably be in the way - then, it will be the job of the connection point function to determine the actual location of the route endpoint taking the respective end element into account.) Anchors are set via an anchor property provided within link end definitions (i.e. the objects provided to link.source() and link.target() functions).

There are many built-in anchor functions in JointJS:

Example:

link.source(model, {
    anchor: {
        name: 'midSide',
        args: {
            rotate: true,
            padding: 20
        }
    }
});

The default anchor function is 'center'; this can be changed with the defaultAnchor paper option. Example:

paper.options.defaultAnchor = {
    name: 'midSide',
    args: {
        rotate: true,
        padding: 20
    }
};

JointJS also contains mechanisms to define one's own custom anchor functions.

anchors.bottom

The 'bottom' anchor function places the anchor of the link in the middle of the bottom side of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'bottom',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.bottomLeft

The 'bottomLeft' anchor function places the anchor of the link at the bottom-left corner of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'bottomLeft',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.bottomRight

The 'bottomRight' anchor function places the anchor of the link at the bottom-left corner of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'bottomRight',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.center

The 'center' anchor function is the default anchor function. It places the anchor of the link at center of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'center',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.custom

New anchor functions can be defined in the joint.anchors namespace (e.g. joint.anchors.myAnchor) or passed directly as a function to the anchor property of link source/target (or to the defaultAnchor option of a paper).

In either case, the anchor function must return the anchor as a Point. The function is expected to have the form function(endView, endMagnet, anchorReference, args):

endView dia.ElementView The ElementView to which we are connecting. The Element model can be accessed as endView.model; this may be useful for writing conditional logic based on element attributes.
endMagnet SVGElement The SVGElement in our page that contains the magnet (element/subelement/port) to which we are connecting.
anchorReference g.Point A reference to another component of the link path that may be necessary to find this anchor point. If we are calling this method for a source anchor, it is the first vertex, or if there are no vertices the target anchor. If we are calling this method for a target anchor, it is the last vertex, or if there are no vertices the source anchor...
SVGElement ...if the anchor in question does not exist (yet), it is that link end's magnet.
args object An object with additional optional arguments passed to the anchor method by the user when it was called (the args property).

anchors.left

The 'left' anchor function places the anchor of the link in the middle of the left side of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'left',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.midSide

The 'midSide' anchor function places the anchor of the link in the middle of the side of view bbox closest to the other endpoint. It accepts two arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
padding number Offset the anchor by padding away from view bbox. Default is 0.

Example:

link.source(model, {
    anchor: {
        name: 'midSide',
        args: {
            rotate: true,
            padding: 20
        }
    }
});

anchors.modelCenter

The 'modelCenter' anchor function places the anchor of the link at center of the model bbox.

Example:

link.source(model, {
    anchor: {
        name: 'modelCenter'
    }
});

anchors.perpendicular

The 'perpendicular' anchor function tries to place the anchor of the link inside the view bbox so that the link is made orthogonal. The anchor is placed along two line segments inside the view bbox (between the centers of the top and bottom side and between the centers of the left and right sides). If it is not possible to place the anchor so that the link would be orthogonal, the anchor is placed at the center of the view bbox instead. The function accepts one argument, which can be passed within the anchor.args property:

padding number Limit the area inside the view bbox available for placing the anchor by padding. Default is 0.

Example:

link.source(model, {
    anchor: {
        name: 'perpendicular',
        args: {
            padding: 10
        }
    }
});

anchors.right

The 'right' anchor function places the anchor of the link in the middle of the right side of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'right',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.top

The 'top' anchor function places the anchor of the link in the middle of the top side of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'top',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.topLeft

The 'topLeft' anchor function places the anchor of the link at the top-left corner of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'topLeft',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

anchors.topRight

The 'topRight' anchor function places the anchor of the link at the top-right corner of the view bbox. It accepts three arguments, which can be passed within the anchor.args property:

rotate boolean Should the anchor bbox rotate with the end view? Default is false, meaning that the unrotated bbox is used.
dx number Offset the anchor by dx. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
dy number Offset the anchor by dy. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.

Example:

link.source(model, {
    anchor: {
        name: 'topRight',
        args: {
            rotate: true,
            dx: 10,
            dy: '40%'
        }
    }
});

connectionPoints

A link connection point is an endpoint of the link route. This point is (usually) different from the link anchor point, as it takes into account the presence of the end element. Connection points are set via an connectionPoint property provided within link end definitions (i.e. the objects provided to link.source() and link.target() functions).

The built-in functions work by finding an intersection between the link path (the path from the link's source anchor, through its vertices, to its target anchor). However, the functions always only have access to a single path segment; the source connectionPoint is found by investigating the first segment (i.e. source anchor - first vertex, or source anchor - target anchor if there are no vertices), while the target connectionPoint is found by investigating the last segment (i.e. last vertex - target anchor, or source anchor - target anchor). This has consequences if the investigated path segment is entirely contained within the end element.

There are four built-in connection point functions in JointJS:

Example:

link.source(model, {
    connectionPoint: {
        name: 'boundary',
        args: {
            sticky: true
        }
    }
});

The default connection point is 'bbox'; this can be changed with the defaultConnectionPoint paper option. Example:

paper.options.defaultConnectionPoint = {
    name: 'boundary',
    args: {
        sticky: true
    }
};

All four of the built-in connection point functions accept the following optional argument, in addition to their own arguments:

offset number Offset the connection point from the anchor by the specified distance along the end link path segment. Default is 0.

Example:

link.source(model, {
    connectionPoint: {
        name: 'bbox',
        args: {
            offset: 10
        }
    }
});

JointJS also contains mechanisms to define one's own custom connection point functions.

connectionPoints.anchor

The 'anchor' connection point function is the simplest connection point function. It places the connection point at the link end's anchor point (determined either by the anchor function or by the defaultAnchor paper option).

Example:

link.source(model, {
    connectionPoint: {
        name: 'anchor',
        args: {
            offset: 10
        }
    }
});

connectionPoints.bbox

The 'bbox' connection point function is the default connection point function. It places the connection point at the intersection between the link path end segment and the end element bbox. It accepts one additional argument, which can be passed within the connectionPoint.args property:

stroke boolean Should the stroke width be included when calculating the connection point? Default is false.

Example:

link.source(model, {
    connectionPoint: {
        name: 'bbox',
        args: {
            offset: 10,
            stroke: true
        }
    }
});

connectionPoints.boundary

The 'boundary' connection point function places the connection point at the intersection between the link path end segment and the actual shape of the end element. (If JointJS is unable to determine the actual shape - e.g. for text - the element bbox is used instead, just as in the 'bbox' connection point function.) It accepts six additional arguments, which can be passed within the connectionPoint.args property:

insideout boolean What happens if the link path never leaves the interior area of the end element (e.g. because the other end anchor lies within the first end element)? Should the path line be extended until an intersection with the boundary is found? Default is true.
extrapolate boolean What happens if the link path never enters the interior area of the end element (e.g. because the anchor lies outside the end element)? Should the path line be extended to try and find the boundary? Default is false. Note that even if this option is true, an intersection is still not guaranteed. This option takes precedence over connectionPoint.args.sticky.
sticky boolean What happens if the link path never enters the interior area of the end element (e.g. because the anchor lies outside the end element)? Should the closest point on the end element boundary be used instead? Default is false. Note that setting this option to true guarantees that a connection point will be found on the shape boundary.
precision number The precision of the path intersection algorithm. Uses a logarithmic scale; increasing the number by 1 reduces the maximum observed error by a factor of ten. Default is 2, corresponding to 1% error.
selector string A selector to identify subelement/magnet of the end element at whose boundary we want the connection point to be found. Default is undefined, meaning that the first non-group descendant of the end element's node will be considered. (An example of another setting that may be useful is 'root', which forces the usage of the root group bbox instead.)
stroke boolean Should the stroke width be included when calculating the connection point? Default is false.

Example:

link.source(model, {
    connectionPoint: {
        name: 'boundary',
        args: {
            offset: 10,
            insideout: false,
            extrapolate: true,
            sticky: true,
            precision: 3,
            stroke: true
        }
    }
});

connectionPoints.custom

New connection point function can be defined in the joint.connectionPoints namespace (e.g. joint.connectionPoints.myConnectionPoint) or passed directly as a function to the connectionPoint property of link source/target (or to the defaultConnectionPoint option of a paper).

In either case, the connection point function must return the connection point as a Point. The function is expected to have the form function(endPathSegmentLine, endView, endMagnet, args):

endPathSegmentLine g.Line The link path segment at which we are finding the connection point. If we are calling this method for a source connection point, it is the first segment (source anchor - first vertex, or source anchor - target anchor). If we are calling this method for a target connection point, it is the last segment (last vertex - target anchor, or source anchor - target anchor).
endView dia.ElementView The ElementView to which we are connecting. The Element model can be accessed as endView.model; this may be useful for writing conditional logic based on element attributes.
endMagnet SVGElement The SVGElement in our page that contains the magnet (element/subelement/port) to which we are connecting.
args object An object with additional optional arguments passed to the connection point method by the user when it was called (the args property).

connectionPoints.rectangle

The 'rectangle' connection point function places the connection point at the intersection between the link path end segment and the element's unrotated bbox. It accepts one additional argument, which can be passed within the connectionPoint.args property:

stroke boolean Should the stroke width be included when calculating the connection point? Default is false.

Example:

link.source(model, {
    connectionPoint: {
        name: 'rectangle',
        args: {
            offset: 10,
            stroke: true
        }
    }
});

connectionStrategies

Connection strategies come into play when the user modifies the position of link endpoints. There are two situations in which this is relevant:

  • When the user drags a link endpoint and connects it to an element or its port. The connection strategy determines the end anchor after the user is finished dragging the link endpoint. (Note that any individual anchor property that might have been assigned on the dragged link endpoint will be overridden by the connection strategy. If necessary, have a look at the custom connectionStrategy documentation for information on replicating the functionality of anchor functions.)
  • When a user creates a link, for example by clicking a port. The connection strategy determines the new link's source anchor.

Both the anchor and connectionPoint properties are rewritten in response to user interaction. None of the built-in connection strategies preserve the originally assigned anchor and connection point functions. To assign precisely what you need as the anchor and connection point functions, you may need to define your own custom connection strategy.

Connection strategies are not assigned on a link-by-link basis. They are set with the connectionStrategy option on a paper.

There are three built-in connection strategies in JointJS:

The default connection strategy is specified as null in paper settings, which is equivalent to joint.connectionStrategies.useDefaults.

Built-in connection strategies are specified by reference to their their name in the joint.connectionStrategies namespace. Example:

paper.options.connectionStrategy = joint.connectionStrategies.pinAbsolute;

connectionStrategies.custom

New connection strategies can be defined in the joint.connectionStrategies namespace (e.g. joint.connectionStrategies.myConnectionStrategy) or passed directly as a function to the connectionStrategy option of a paper.

In either case, the connection strategy function must return an end definition (i.e. an object in the format supplied to the link.source() and link.target() functions). The function is expected to have the form function(endDefinition, endView, endMagnet, coords):

endDefinition object An end definition; the output of the appropriate end function (link.source() or link.target()). An object containing at least an id of the Element to which we are connecting. This object is expected to be changed by this function and then sent as the return value.
endView dia.ElementView The ElementView to which we are connecting. The Element model can be accessed as endView.model; this may be useful for writing conditional logic based on element attributes.
endMagnet SVGElement The SVGElement in our page that contains the magnet (element/subelement/port) to which we are connecting.
coords g.Point A Point object recording the x-y coordinates of the user pointer when the connection strategy was invoked.

Custom connection strategies may be enormously useful for your users. Here we provide some examples of custom functionality.

Connecting to Ancestors

If your diagram makes heavy use of nested elements, it may be useful to always connect links to a top-level ancestor element (instead of the element on which the arrowhead was actually dropped by user interaction):

joint.connectionStrategies.topAncestor = function(end, endView) {

    var ancestors = endView.model.getAncestors();
    var numAncestors = ancestors.length;
    var end = numAncestors ? ancestors[numAncestors - 1] : end;

    return end;
}

paper.options.connectionStrategy = joint.connectionStrategies.topAncestor;

Connecting to Ports

If your diagram uses ports, you usually do not want links to be able to connect anywhere else. The solution is similar to the one above:

joint.connectionStrategies.firstPort = function(end, endView) {

    var ports = endView.model.getPorts();
    var numPorts = ports.length;
    var end = numPorts ? { id: end.id, port: ports[0].id } : end;

    return end;
}

paper.options.connectionStrategy = joint.connectionStrategies.firstPort;

Replicating Built-in Anchor Functions

Furthermore, it is very easy to replicate the built-in anchor functions for connection strategy scenarios - simply apply the anchor function to the received end parameter:

joint.connectionStrategy.midSide = function(end) {

    end.anchor = {
        name: 'midSide',
        args: {
            rotate: true
        }
    };

    return end;
}

paper.options.connectionStrategy = joint.connectionStrategy.midSide;

Replicating Built-in Connection Point Functions

What if we needed to replicate a built-in connection point function instead? We use the same idea as in the previous example:

joint.connectionStrategy.boundary = function(end) {

    end.connectionPoint = {
        name: 'boundary',
        args: {
            offset: 5
        }
    };

    return end;
}

paper.options.connectionStrategy = joint.connectionStrategy.boundary;

Of course, it is also possible to combine both of the examples and assign an anchor as well as connectionPoint to the end parameter of the modified link.

connectionStrategies.pinAbsolute

The pinAbsolute connection strategy records the coordinates of user pointer and assigns the end anchor absolutely, by reference to the top-left corner of the view bbox of the element above which the endpoint was dropped. Absolute positioning ensures that if the element is subsequently resized, the anchor stays at the same absolute distance from the edges (e.g. staying 10 pixels away from the left side and 20 pixels away from the top side).

The end connection point is assigned according to defaultConnectionPoint paper option.

Example:

paper.options.connectionStrategy = joint.connectionStrategies.pinAbsolute;

The end (source or target) that is being modified gets the 'topLeft' anchor assigned by this connection strategy:

end.anchor = {
    name: 'topLeft',
    args: {
    	rotate: true
        dx: (coords.x - bbox.x),
        dy: (coords.y - bbox.y)
    }
};

connectionStrategies.pinRelative

The pinRelative connection strategy records the coordinates of user pointer and assigns the end anchor relatively, by reference to the top-left corner of the view bbox of the element above which the endpoint was dropped. Relative positioning ensures that if the element is subsequently resized, the anchor stays at the same relative distance from the edges (e.g. staying 25% of the way from the left side and 75% of the way from the top side).

The end connection point is assigned according to defaultConnectionPoint paper option.

Example:

paper.options.connectionStrategy = joint.connectionStrategies.pinRelative;

The end (source or target) that is being modified gets the 'topLeft' anchor assigned by this connection strategy:

end.anchor = {
    name: 'topLeft',
    args: {
    	rotate: true
        dx: percentageString(coords.x - bbox.x),
        dy: percentageString(coords.y - bbox.y)
    }
};

connectionStrategies.useDefaults

The useDefaults connection strategy is the simplest connection strategy. It ignores the coordinates of user pointer and assigns the end anchor according to the defaultAnchor paper option and the end connection point according to the defaultConnectionPoint paper option.

Thus, this connection strategy is equivalent to a connection strategy of null.

Example:

paper.options.connectionStrategy = joint.connectionStrategies.useDefaults;

connectors

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.

There are four built-in connectors in JointJS:

Example:

link.connector('rounded', {
    radius: 20
});

The default connector is 'normal'; this can be changed with the defaultConnector paper option. Example:

paper.options.defaultConnector = {
    name: 'rounded',
    args: {
        radius: 20
    }
}

All four of the built-in connectors accept the following optional argument, in addition to their own arguments:

raw boolean Should the router return the connection path as a g.Path rather than as a string? Default is false.

Example:

link.connector('normal', {
    raw: true
});

JointJS also contains mechanisms to define one's own custom connectors.

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');

connectors.custom

New connectors can be defined in the joint.connectors namespace (e.g. joint.connectors.myConnector) or passed directly as a function to the connector property of a link (or to the defaultConnector paper option).

In either case, the connector function must return a g.Path representing the SVG path data that will be used to render the link. The function is expected to have the form function(sourcePoint, targetPoint, routePoints, args):

sourcePoint g.Point The source connection point.
targetPoint g.Point The target connection point.
routePoints Array<g.Point> The points of the route, as returned by the router in use.
args object An object with additional optional arguments passed to the connector method by the user when it was called (the args property).

Example of a connector defined in the joint.connectors namespace:

joint.connectors.wobble = function(sourcePoint, targetPoint, vertices, args) {

    var SPREAD = args.spread || 20;

    var points = vertices.concat(targetPoint)
    var prev = sourcePoint;
    var path = new g.Path(g.Path.createSegment('M', prev));

    var n = points.length;
    for (var i = 0; i < n; i++) {

        var next = points[i];
        var distance = prev.distance(next);

        var d = SPREAD;
        while (d < distance) {
            var current = prev.clone().move(next, -d);
            current.offset(
                Math.floor(7 * Math.random()) - 3,
                Math.floor(7 * Math.random()) - 3
            );
            path.appendSegment(g.Path.createSegment('L', current));
            d += SPREAD;
        }

        path.appendSegment(g.Path.createSegment('L', next));
        prev = next;
    }

    return path;
}

var link = new joint.shapes.standard.Link();
link.source(source);
link.target(target);

link.connector('wobble', {
    spread: 10
});

An example of a connector passed as a function is provided below. Notice that this approach does not enable passing custom args nor can it be serialized with the graph.toJSON() function.

var link = new joint.shapes.standard.Link();
link.source(source);
link.target(target);

link.connector(function(sourcePoint, targetPoint, vertices, args) {

    var SPREAD = 20;

    var points = vertices.concat(targetPoint)
    var prev = sourcePoint;
    var path = new g.Path(g.Path.createSegment('M', prev));

    var n = points.length;
    for (var i = 0; i < n; i++) {

        var next = points[i];
        var distance = prev.distance(next);

        var d = SPREAD;
        while (d < distance) {
            var current = prev.clone().move(next, -d);
            current.offset(
                Math.floor(7 * Math.random()) - 3,
                Math.floor(7 * Math.random()) - 3
            );
            path.appendSegment(g.Path.createSegment('L', current));
            d += SPREAD;
        }

        path.appendSegment(g.Path.createSegment('L', next));
        prev = next;
    }

    return path;
});

connectors.jumpover

The 'jumpover' connector draws straight lines with small arcs in place of link-link intersections. (For the time being, it cannot detect intersections with 'smooth' router links). It accepts the following additional arguments, which can be passed as the connector.args property:

size number The size of the jump (the diameter of the arc, or the length of the empty spot on the line). Defaults to 5.
jump string The style of the jump. Either 'arc' (using an Arcto SVG path command), 'cubic' (using a Curveto path command as a normalized approximation to Arcto), or 'gap' (leaving a blank space). Defaults to 'arc'.

Example:

link.connector('jumpover', {
    type: 'gap'
});

connectors.normal

The 'normal' connector is the default connector for links and it is the simplest connector. It simply connects provided route points with straight-line segments.

Example:

link.connector('normal');

connectors.rounded

The 'rounded' connector connects provided route points with straight lines while smoothing all corners on the route. It accepts one additional argument, which can be passed within the connector.args property:

radius boolean The curve radius of the rounded corners. Default is 10.

Example:

link.connector('rounded', {
    radius: 20
});

connectors.smooth

The 'smooth' connector interpolates route points using a cubic bezier curve.

Example:

link.connector('smooth');

(Deprecated) For the purposes of backwards compatibility, the 'smooth' connector may also be enabled by setting the link.smooth property to true.

// deprecated
link.set('smooth', true)

dia.attributes

The attributes in JointJS define how the graphics elements are to be rendered inside of the element and link views. All the standard SVG styling properties are available (both kebab-case and camelCase styles). In addition JointJS defines new so-called "special" attributes and allows programmers to define their own. Here is the list of all built-in attributes.

dia.attributes.atConnectionLengthIgnoreGradient

Move the subelement to the point at a given distance along the connection path but do not auto-orient it according to the path's gradient. Use a positive number to define the distance from the source of the link and a negative number from the target of the link. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionLengthIgnoreGradient: 30, width: 10, height: 10, fill: 'red' });

dia.attributes.atConnectionLengthKeepGradient

alias: atConnectionLength

Move and auto-orient the subelement to the point at a given distance along the connection path. Use a positive number to define the distance from the source of the link and a negative number from the target of the link. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionLength: 30, width: 10, height: 10, fill: 'red' });
link.attr('rectSelector', { atConnectionLengthKeepGradient: 30, width: 10, height: 10, fill: 'red' });

dia.attributes.atConnectionRatioIgnoreGradient

Move the subelement to the point at a given ratio of the connection total length but do not auto-orient it according to the path's gradient. It accepts a number in the [0,1] range. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionRatioKeepGradient: .5, width: 10, height: 10, fill: 'red' });

dia.attributes.atConnectionRatioKeepGradient

alias: atConnectionRatio

Move and auto-orient the subelement to the point at a given ratio of the connection total length. It accepts a number in the [0,1] range. It is valid only within the LinkView context.

link.attr('rectSelector', { atConnectionRatio: .5, width: 10, height: 10, fill: 'red' });
link.attr('rectSelector', { atConnectionRatioKeepGradient: .5, width: 10, height: 10, fill: 'red' });

dia.attributes.connection

Set the 'd' attribute based on the current link connection (the result of the link`s connector). It's valid only for SVGPathElement within the LinkView context.

link.attr('pathSelector', { connection: true, stroke: 'red', fill: 'none' });

dia.attributes.event

The event attribute makes the selected node and its descendants trigger an arbitrary event when clicked (mousedown/touchstart). This event is triggered on the view itself and the paper. The paper handler is called with the signature cellView, evt, x, y, while the cell view handler is called only with evt, x, y.

element.attr({
  image: {
    // pointerdown on the image SVG node will trigger the `element:delete` event
    event: 'element:delete',
    xlinkHref: 'trash.png'
    width: 20,
    height: 20
  }
});
// Binding handler to the event
paper.on('element:delete', function(elementView, evt) {
  // Stop any further actions with the element view e.g. dragging
  evt.stopPropagation();
  if (confirm('Are you sure you want to delete this element?')) {
      elementView.model.remove();
  }
});

dia.attributes.fill

The fill attribute becomes a special attribute only in case it's defined as an object, instead of the usual SVG syntax (e.g. "#ffaabb"). If it's defined as an object, it is assumed to be a gradient definition and must have the form defined by the defineGradient() paper method.

element.attr('rect/fill', {
    type: 'linearGradient',
    stops: [
        { offset: '0%', color: '#E67E22' },
        { offset: '20%', color: '#D35400' },
        { offset: '40%', color: '#E74C3C' },
        { offset: '60%', color: '#C0392B' },
        { offset: '80%', color: '#F39C12' }
    ]
});

dia.attributes.filter

The filter attribute becomes a special attribute only in case it's defined as an object, instead of the usual SVG syntax (e.g. "url(#myfilter)"). If it's defined as an object, it must have the form defined by by the filterGradient() paper method.

element.attr('rect/filter', {
    name: 'dropShadow',
    args: {
        dx: 2,
        dy: 2,
        blur: 3
    }
});

dia.attributes.magnet

When set to true, the subelement can become a source/target of a link during link reconnection. Useful for so called 'ports'.

dia.attributes.port

An object containing at least an id property. This property uniquely identifies the port. If a link gets connected to a magnet that has also a port object defined, the id property of the port object will be copied to the port property of the source/target of the link.

dia.attributes.ref

CSS selector pointing to an element that is used as a reference for relative positioning attributes.

dia.attributes.refCx

Set cx attribute of the subelement relatively to the width of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the cx of the subelement will be set as a percentage of the width of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the width of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

dia.attributes.refCy

Set cy attribute of the subelement relatively to the height of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the cy of the subelement will be set as a percentage of the height of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the height of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

dia.attributes.refDKeepOffset

Set d attribute of the <path> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refD path data is scaled so that the path's dimensions match the reference element's dimensions, and translated so that the path's origin matches the origin of the reference element.

The original path data offset is preserved. This means that if the top-left corner of the refD bounding box does not lie at 0,0, the gap between the path and origin is preserved in the rendered shape, as well.

var Path = joint.dia.Element.define('examples.Path', {
    attrs: {
        path: {
            refDKeepOffset: 'M 10 10 30 10 30 30 z', // path offset is 10,10
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'path'
});

var p = (new Path()).resize(40, 40).addTo(graph);
// the rendered path's `d` attribute will be 'M 10 10 50 10 50 50 z'
// can be obtained by `p.findView(paper).vel.findOne('path').attr('d');`

dia.attributes.refDResetOffset

alias: refD

Set d attribute of the <path> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refD path data is scaled so that the path's dimensions match the reference element's dimensions, and translated so that the path's origin matches the origin of the reference element.

The original path data offset is not preserved. This means that if the top-left corner of the refD bounding box does not lie at 0,0, the path is translated so that this gap disappears. The rendered path then fits perfectly into the reference element's bounding box.

var Path = joint.dia.Element.define('examples.Path', {
    attrs: {
        path: {
            refDResetOffset: 'M 10 10 30 10 30 30 z', // path offset of 10,10 will be discarded
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'path'
});

var p = (new Path()).resize(40, 40).addTo(graph);
// the rendered path's `d` attribute will be 'M 0 0 40 0 40 40 z'
// can be obtained by `p.findView(paper).vel.findOne('path').attr('d');`

dia.attributes.refDx

alias: ref-dx

Make x-coordinate of the subelement relative to the right edge of the element referenced to by the selector in ref attribute.

dia.attributes.refDy

Make y-coordinate of the subelement relative to the bottom edge of the element referenced to by the selector in ref attribute.

dia.attributes.refHeight

alias: ref-height

Set height of the subelement relatively to the height of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the height of the subelement will be set as a percentage of the height of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the height of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support width and height attributes, such as <rect>.

dia.attributes.refPointsKeepOffset

Set the points attribute of the <polygon> or <polyline> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refPoints are scaled so that the subelement's dimensions match the reference element's dimensions, and translated so that the their origin matches the origin of the reference element.

The original points offset is preserved. This means that if the top-left corner of the refPoints bounding box does not lie at 0,0, the gap between the points and origin is preserved in the rendered shape, as well.

var Polygon = joint.dia.Element.define('examples.Polygon', {
    attrs: {
        polygon: {
            refPoints: '10,10 30,10 30,30', // points offset is 10,10
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'polygon'
});

var p = (new Polygon()).resize(40, 40).addTo(graph);
// the rendered polygon's `points` attribute will be '10,10 50,10 50,50'
// can be obtained by `p.findView(paper).vel.findOne('polygon').attr('points');`

dia.attributes.refPointsResetOffset

alias: refPoints

Set the points attribute of the <polygon> or <polyline> subelement relatively to the dimensions and position of the element referenced by the selector in the ref attribute. The refPoints are scaled so that the subelement's dimensions match the reference element's dimensions, and translated so that the their origin matches the origin of the reference element.

The original points offset is not preserved. This means that if the top-left corner of the refPoints bounding box does not lie at 0,0, the subelement is translated so that this gap disappears. The rendered subelement then fits perfectly into the reference element's bounding box.

var Polygon = joint.dia.Element.define('examples.Polygon', {
    attrs: {
        polygon: {
            refPoints: '10,10 30,10 30,30', // points offset of 10,10 will be discarded
            fill: 'red',
            stroke: 'black'
        }
    }
}, {
    markup: 'polygon'
});

var p = (new Polygon()).resize(40, 40).addTo(graph);
// the rendered polygon's `points` attribute will be '0,0 40,0 40,40'
// can be obtained by `p.findView(paper).vel.findOne('polygon').attr('d');`

dia.attributes.refRCircumscribed

Set the r attribute of the subelement relatively to the circumscribed size (length of the diagonal of the bounding box) of the element referenced by the selector in the ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the r of the subelement will be set as a percentage of the size of the referenced element. If the value is <0 or >1, the size of the subelement will be smaller/bigger than the size of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support r attribute, such as <circle>.

dia.attributes.refRInscribed

alias: refR

Set the r attribute of the subelement relatively to the inscribed size (width or height of the bounding box, whichever is smaller) of the element referenced by the selector in the ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the r of the subelement will be set as a percentage of the size of the referenced element. If the value is <0 or >1, the size of the subelement will be smaller/bigger than the size of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support r attribute, such as <circle>.

dia.attributes.refRx

Set rx attribute of the subelement relatively to the width of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the rx of the subelement will be set as a percentage of the width of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the width of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

dia.attributes.refRy

Set ry attribute of the subelement relatively to the height of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the ry of the subelement will be set as a percentage of the height of the referenced element. If the value is <0 or >1, the height of the subelement will be smaller/bigger than the height of the referenced element by the amount specified. Note that this makes sense only for SVG elements that support rx and ry attributes, such as <ellipse>.

dia.attributes.refWidth

alias: ref-width

Set width of the subelement relatively to the width of the element referenced to by the selector in ref attribute. If the value is in the [0, 1] interval (or expressed in percentages, e.g. '80%'), the width of the subelement will be set as a percentage of the width of the referenced element. If the value is <0 or >1, the width of the subelement will be smaller/bigger than the width of the referenced element by the amount specified. For example, 'ref-width': .75 sets the width of the subelement to 75% of the width of the referenced element. 'ref-width': 20 makes the width to be 20px less than the width of the referenced element. Note that this makes sense only for SVG elements that support width and height attributes, such as <rect>.

dia.attributes.refX

alias: ref-x

Make x-coordinate of the subelement relative to the x-coordinate of the element referenced to by the selector in ref attribute. If ref-x is in the (0,1) interval (or expressed in percentages, e.g. '80%'), the offset is calculated from the fraction of the bounding box of the referenced element. Otherwise, it is an absolute value in pixels.

dia.attributes.refX2

Same as refX. Useful when one needs to position an element absolutely and relatively at the same time.

{ refX: '50%', refX2: 20 } // moves the element by 50% of the referenced width plus extra 20 pixels.

dia.attributes.refY

alias: ref-y

Make y-coordinate of the subelement relative to the y-coordinate of the element referenced to by the selector in ref attribute. If ref-y is in the (0,1) interval (or expressed in percentages, e.g. '80%'), the offset is calculated from the fraction of the bounding box of the referenced element. Otherwise, it is an absolute value in pixels.

dia.attributes.refY2

Same as refY. Useful when one needs to position an element absolutely and relatively at the same time.

{ refY: '50%', refY2: 20 } // moves the element by 50% of the referenced height plus extra 20 pixels.

dia.attributes.resetOffset

If set to true, the subelement offset (the distance from x0 y0 to the most top-left point) will be reset to x0 y0.

element.attr({
  path: {
    // The path bbox for `d="M 10 10 20 20"` is x10 y10 w10 h10.
    d: 'M 10 10 20 20',
    // The path bbox will be changed to x0 y0 w10 h10.
    // This has same effect as passing path with `d="M 0 0 10 10"`
    resetOffset: true
  }
});

dia.attributes.sourceMarker

Valid for <path> subelements. It draws an SVG element at the beginning of a path. The element is automatically rotated based on the path direction. It's defined as an object with type property and any other visual attributes. The valid values for type are 'path', 'circle', 'ellipse', 'rect', 'polyline' and 'polygon'.

link.attr('.connection/sourceMarker', {
  type: 'circle', // SVG Circle
  fill: '#666',
  stroke: '#333',
  r: 5, // radius of the circle
  cx: 5 // move the centre of the circle 5 pixels from the end of the path
});

dia.attributes.stroke

The stroke attribute becomes a special attribute only in case it's defined as an object. This has the exact same behaviour as the fill attribute.

dia.attributes.style

An object containing CSS styles for a subelement.

dia.attributes.targetMarker

Valid for <path> subelements. The same as sourceMarker but draws an SVG element at the end of the path. Note the coordinate system for drawing is rotated by 180 degrees for convenience (this allows to use the same marker for source and target and have them both face the connected elements).

dia.attributes.text

Valid only for <text> subelements. text attribute contains the text that will be set either directly to the <text> subelement or its <tspan> children depending on whether the text is multiline or not (contains '\n' character(s)).

dia.attributes.textPath

Valid only for <text> subelements. textPath can be either a string or an object.

If it is a string, it specifies a path the text will be rendered along.

If it is an object, then it can contain a d property that specifies the path the text will be rendered along. Alternatively use selector property, which is useful for targeting a specific SVGPathElement within the shape. The option expects a string selector (CSS or JSONMarkup selector). Use startOffset property to control the text position on the path (e.g. '50%', 20). See the Vectorizer.text method for more details.

dia.attributes.textVerticalAnchor

Valid only for <text/> subelements. The attribute is used to (top-, middle- or bottom-) align a text, relative to a point determined by reference to provided x, y, refX, refY, and similar attributes. See the Vectorizer.text method for more details.

dia.attributes.textWrap

Valid for <text> subelements. Similar to text attribute but in this case the text is automatically wrapped to fit within the reference bounding box. It's defined as an object with text property and optional width and height, which can adjust the final size of the wrapped text. Positive values increment and negative values decrement the dimension. Define values as percentage when a fraction of the dimension is required.

textWrap: {
  text: 'Here is the text to be wrapped.',
  width: -10, // reference width minus 10
  height: '50%' // half of the reference height
}

dia.attributes.title

Add the text-only description in form of a <title> element to the associated node. The title is not rendered as part of the graphics, but it's displayed as a tooltip.

element.attr('rect/title', 'Description of the rectangle');

dia.attributes.vertexMarker

Valid for <path> subelements. The same as sourceMarker but draws SVG elements at every vertex of the path.

dia.attributes.xAlignment

alias: x-alignment

If set to 'middle', the subelement will be centered around its new x-coordinate.

dia.attributes.yAlignment

alias: y-alignment

If set to 'middle', the subelement will be centered around its new y-coordinate.

dia.Cell

The basic model for diagram cells. It's a Backbone model with a few additional properties and methods. Most importantly, every cell has a unique ID that is stored in the id property.

dia.Cell.define

define(type [, defaultAttributes, prototypeProperties, staticProperties])

Helper to define a new Cell class or extend an existing one.

The type must be a unique identifier of the class, which determines the location of the class definition in the joint.shapes namespace (type is the path to the class definition delimited by dots: .). When creating an instance of the cell, attributes will be set to the value from the defaultAttributes, unless overridden by subclass or instance attributes.

// Define a new Ellipse class in `joint.shapes.examples` namespace
// Inherits from generic Element class
var Ellipse = joint.dia.Element.define('examples.Ellipse', {
    // default attributes
    markup: [{
        tagName: 'ellipse',
        selector: 'ellipse' // not necessary but faster
    ],
    attrs: {
        ellipse: {
            fill: 'white',
            stroke: 'black',
            strokeWidth: 4,
            refRx: .5,
            refRy: .5,
            refCx: .5,
            refCy: .5
        }
    }
});

// Instantiate an element
var ellipse = (new Ellipse()).position(100, 100).size(120, 50).addTo(graph);

// Define a new ColoredEllipse class
// Inherits from Ellipse
var ColoredEllipse = Ellipse.define('examples.ColoredEllipse', {
    // overridden Ellipse default attributes
    // other Ellipse attributes preserved
    attrs: {
        ellipse: {
            fill: 'lightgray'
        }
    }
}, {
    // prototype properties
    // accessible on `this.(...)` - as well as, more precisely, `this.prototype.(...)`
    // useful for custom methods that need access to this instance
    // shared by all instances of the class
    randomizeStrokeColor: function() {
        var randomColor = '#' + ('000000' + Math.floor(Math.random() * 16777215).toString(16)).slice(-6);
        return this.attr('ellipse/stroke', randomColor);
    }
}, {
    // static properties
    // accessible on `this.constructor.(...)`
    // useful for custom methods and constants that do not need an instance to operate
    // however, a new set of static properties is generated every time the constructor is called
    // (try to only use static properties if absolutely necessary)
    createRandom: function() {
        return (new ColoredEllipse()).randomizeStrokeColor();
    }
});

// Instantiate an element
var coloredEllipse = ColoredEllipse.createRandom().position(300, 100).size(120, 50).addTo(graph);

dia.Cell.markup

markup

Either an XML string or JSON markup specifying an array of JSON elements. Used as a template to build DOM Elements on the fly when the associated cellView is rendered.

XML String

A valid XML string that contains either a single tagName or XML that can be parsed with DOMParser.

markup: 'rect'
markup: '<rect class="rectangle"/>'
markup: '<rect><g><circle/><circle/></g>'

JSON Markup

JSON markup is defined recursively as an array of JSONElement, where JSONElement is a plain object with the following properties:

  • tagName (string) (required) The type of element to be created.
  • selector (string) A selector for targeting the element within the attr cell attribute.
  • namespaceURI (string) The namespace URI of the element. It defaults to SVG namespace "http://www.w3.org/2000/svg".
  • attributes (object with attributes name-value pairs) Attributes of the element.
  • style (object with CSS property-value pairs) The style attribute of the element.
  • className (string) The class attribute of the element.
  • children (JSONMarkup) The children of the element.
// single DOM element
markup: [{ tagName: 'rect' }]

// multiple DOM elements
markup: [{
    tagName: 'rect',
    selector: 'body'
}, {
    tagName: 'text',
    selector: 'label',
    attributes: {
        'stroke': 'none'
    }
}]

// nested DOM elements
markup: [{
    tagName: 'g',
    children: [{
        tagName: 'circle',
        selector: 'circle1'
    }, {
        tagName: 'circle',
        selector: 'circle2'
    }]
}]
dia.Cell.prototype.getParentCell
cell.getParentCell()

Return the parent cell of cell or null if there is none.

dia.Cell.prototype.isElement
cell.isElement()

Always returns false. The reason the method is here is that both joint.dia.Element and joint.dia.Link inherit from joint.dia.Cell. This method is useful if you don't know what the cell is. Calling cell.Element() is equivalent to cell instanceof joint.dia.Element. Example:

var cell = graph.getCell(myId)
if (cell.isElement()) {
    // Do something if the cell is an element.
}
dia.Cell.prototype.parent
cell.parent()

Return the parent property of the cell.

If the cell is a part of an embedding, the id of the parent cell is returned as a string.

If you need to be sure that a Cell is returned (and not its id), use the cell.getParentCell function instead.

cell.parent(parentId [, opt])

Set the parent property of the cell to parentId provided.

dia.CellView

The view for the joint.dia.Cell model. It inherits from Backbone.View and is responsible for:

  • Rendering a cell inside of a paper
  • Handling the cell's pointer events
  • Provides various methods for working with the cell (visually)

To find the view associated with a specific cell (model), use the findViewByModel method of the paper. For example:

var cellView = paper.findViewByModel(cell);
dia.CellView.prototype.highlight
cellView.highlight([el[, options]])

Highlights the cell view.

Arguments:

  • el - if not provided, then the cell view's $el will be used
  • options:
    • highlighter:
      • name - the name of the highlighter (see highlighters)
      • options - an options object that will be passed directly to the highligher specified by name
    • type - the kind of highlighting being done (embedding, connecting, magnetAvailability, or elementAvailability)
dia.CellView.prototype.unhighlight
cellView.unhighlight([el[, options]])

Removes the highlighting being done to the cell.

It is important to note that if you highlighted a cell using custom options, you must provide those exact same options when using the unhighlight method.

dia.Element

The model for diagram elements. It inherits from joint.dia.Cell with a few additional properties and methods specific to elements. These properties can be put into three groups:

Geometry

Coordinates of an element are stored in the position property that is an object with x and y keys. position can be accessed or set directly using the regular Backbone set()/get() methods or through the translate method.

Rotation angle is stored in the angle property. This angle is in degrees and the rotation origin is always considered to be the center of the element. angle can be also accessed or set directly using the regular Backbone set()/get() methods or through the rotate method.

Size of an element is stored in the size property that is an object with width and height keys. Again, size can be accessed or set directly using the regular Backbone set()/get() methods or through the resize method.

Presentation

Another important property is attrs which is an object with keys representing selectors that match subelements and values which are SVG attributes that will be set on the subelements. One can find a list of SVG attributes and their descriptions e.g. on MDN.

It is important to note that each joint.dia.Element defines an SVG markup which is then used by joint.dia.ElementView to render the element to the paper. For instance, the joint.shapes.basic.Rect element (that inherits from joint.dia.Element) defines its markup as follows:

<g class="rotatable"><g class="scalable"><rect/></g><text/></g>

Therefore, in order to set a red fill color for the rectangle subelement, the attrs object should contain:

rect: { fill: 'red' }

Again, it is not recommended to change the attrs object directly. Instead, use the attr method.

The z property specifies the stack order of the element in the SVG DOM. An element with a higher z level is in front of an element with a lower z level. (This also stands for links which have the exact same property.)

Nesting

The last two properties of elements are embeds and parent. These two are related to elements that contain or are contained within other elements forming a hierarchical structure. embeds is a list of cell id's that are embedded inside the element. parent is an id of the parent element of the embedded one. When a parent element is translated, all its children get translated too.

dia.Element.events

The following list contains events that you can react on:

  • change - generic event triggered for any change on the element - fn(element, opt)
  • change:position - triggered when the element changes its position - fn(element, newPosition, opt)
  • change:angle - triggered when the element gets rotated - fn(element, newAngle, opt)
  • change:size - triggered when the element gets resized - fn(element, newSize, opt)
  • change:attrs - triggered when the element changes its attributes - fn(element, newAttrs, opt)
  • change:embeds - triggered when other cells were embedded into the element - fn(element, newEmbeds, opt)
  • change:parent - triggered when the element got embedded into another element - fn(element, newParent, opt)
  • change:z - triggered when the element is moved in the z-level (toFront and toBack) - fn(element, newZ, opt)
  • transition:start - triggered when a transition starts. - fn(element, pathToAttribute)
  • transition:end - triggered when a transiton ends. - fn(element, pathToAttribute)
// Listening for changes of the position to a single element
element1.on('change:position', function(element1, position) {
  alert('element1 moved to ' + position.x + ',' + position.y);
});
// All elements events are also propagated to the graph.
graph.on('change:position', function(element, position) {
  console.log('Element ' + element.id + 'moved to ' + position.x + ',' + position.y);
});
// Using the option parameter and a custom attribute
graph.on('change:custom', function(element, custom, opt) {
  if (opt.consoleOutput) {
    console.log('Custom attribute value changed to "' + custom + '"');
  }
});
element2.prop('custom', 'myValue', { consoleOutput: true });

dia.Element.ports

Ports

Many diagramming applications deal with elements with ports. Ports are usually displayed as circles inside diagram elements and are used not only as "sticky" points for connected links but they also further structure the linking information. It is common that certain elements have lists of input and output ports. A link might then point not to the element as a whole but to a certain port instead.

It's easy to add ports to arbitrary shapes in JointJS. This can be done either by passing a ports definition as an option in the constructor or using the ports API to get/add/remove single or multiple ports. For more information on how to define ports please see Port configuration section.

Port API on joint.dia.Element
Port configuration
// Single port definition
var port = {
    // id: 'abc', // generated if `id` value is not present
    group: 'a',
    args: {}, // extra arguments for the port layout function, see `layout.Port` section
    label: {
        position: {
            name: 'right',
            args: { y: 6 } // extra arguments for the label layout function, see `layout.PortLabel` section
        },
        markup: '<text class="label-text" fill="blue"/>'
    },
    attrs: { text: { text: 'port1' } },
    markup: '<rect width="16" height="16" x="-8" strokegit ="red" fill="gray"/>'
};

// a.) add a port in constructor.
var rect = new joint.shapes.standard.Rectangle({
    position: { x: 50, y: 50 },
    size: { width: 90, height: 90 },
    ports: {
        groups: {
            'a': {}
        },
        items: [port]
    }
});

// b.) or add a single port using API
rect.addPort(port);
id string It is automatically generated if no id provided. IDs must be unique in the context of a single shape - two ports with the same port id are therefore not allowed (Element: found id duplicities in ports. error is thrown).
group string Group name, more info in groups section.
args object Arguments for the port layout function. Available properties depends on the type of layout. More information could be found in layout.Port.
attrs object JointJS style attribute definition. The same notation as the attrs property on Element.
markup string Custom port markup. Multiple roots are not allowed. Valid notation would be:
<g>
    <rect class="outer" width="15" height="15" fill="red"/>
    <rect class="inner" width="15" height="15" fill="blue" x="10"/>
</g>

It defaults to <circle class="joint-port-body" r="10" fill="#FFFFFF" stroke="#000000"/>.

label object Port label layout configuration. E.g. label position, label markup. More information about port label layouts could be found in layout.PortLabel section.
  • label.position
string | object Port label position configuration. It could be a string for setting the port layout type directly with default settings or an object where it's possible to set the layout type and options.
{ position: 'left'}

// or ...

{
    position: {
        name: 'left',
        args: {
            dx: 10
        }
    }
}
  • label.position.name
string Stands for the layout type, match the layout method name defined in joint.layout.PortLabel namespace: name:'left' is implemented as joint.layout.PortLabel.left.
  • label.position.args
object Additional arguments for the layout method. Available properties depends on the layout type. More information could be found in layout.PortLabel section.
  • label.markup
string Custom port label markup. Multiple roots are not allowed. It defaults to <text class="joint-port-label" fill="#000000"/>.
z number | string

Alternative to HTML z-index. z sets the position of a port in the list of DOM elements within an ElementView.

Shapes most likely consist of 1 or more DOM elements, <rect/>, <rect/><text/><circle/> etc. Ports are placed into the element rotatable group (if there is no rotatable group in the shape's markup, then the main group element elementView.el is used for the port container). Ports with z:'auto' are located right after the last element in the rotatable group. Ports with z defined as a number are placed before a DOM element at the position (index within the children of the container, where only the original markup elements and ports with z:'auto' are taken into account) equals to z.

For instance an element with the following markup

<g class="rotatable">
    <g class="scalable"><rect/></g>
    <text/>
</g>
will be rendered like this:

<g model-id="element1">
    <g class="rotatable">
        <g class="port"></g>         <!-- z: 0 -->
        <g class="scalable"><rect/></g>
        <g class="port"></g>         <!-- z: 1 -->
        <text/>
        <g class="port"></g>         <!-- z: 2 -->
    </g>
</g>

Another example with simplified markup <circle/><text/> can look as follows:

<g model-id="element2">
    <g class="port"></g>         <!-- z: 0 -->
    <circle/>
    <g class="port"></g>         <!-- z: 1 -->
    <g class="port"></g>         <!-- another z: 1 -->
    <text/>
    <g class="port"></g>         <!-- z: 2 -->
    <g class="port"></g>         <!-- z: 'auto' -->
    <g class="port"></g>         <!-- z: 3 -->
    <g class="port"></g>         <!-- z: 'auto' -->
    <g class="port"></g>         <!-- z: 10 -->
</g>

All properties described above are optional and everything has own default. E.g. element.addPorts([{}, {}]) will add 2 ports with default settings.

Port groups configuration

group attribute comes to play when you're not happy with the default port alignment. It's also handy when you need to define multiple ports with similar properties. group defines defaults for ports belonging to the group. Any group property can be overwritten by a port in this group except the type of layout - position. 'group' defines the layout and port 'args' are the only way how a port can affect it.


   // Define ports and port groups in element constructor.
   var groupA;
   var rect = new joint.shapes.basic.Rect({
        // ...
        ports: {
            groups: {
                'group1': groupA,
                // 'group2': ...,
                // 'group3': ...,
            },
            items: []
        }
    });

    groupA = {
            position: {
                name: 'string', // layout name
                args: {}, // arguments for port layout function, properties depends on type of layout
            },
            label: {
                // ....
            },
            attrs: {},
            markup: '<rect width="10" height="10" stroke="red"/>'
        };
position string | object Port position configuration. Could be string to set port layout type directly with default settings or object where is possible to set layout type and options.
  • position.name
string Stands for the layout type, match the layout method name defined in joint.layout.Port namespace: name:'left' is implemented as joint.layout.Port.left.
  • position.args
object Arguments for the port layout function. Available properties depends on the type of layout. More information could be found in layout.Port.
attrs object JointJS style attribute definition. The same notation as the attrs property on Element.
markup string Custom port markup. Multiple roots are not allowed. Valid notation would be:
<g>
    <rect class="outer" width="15" height="15" fill="red"/>
    <rect class="inner" width="15" height="15" fill="red" x="10"/>
</g>
. It defaults to <circle class="joint-port-body" r="10" fill="#FFFFFF" stroke="#000000"/>
label object Port label layout configuration. E.g. label position, label markup. More information about port label layouts could be found in layout.PortLabel section.
  • label.position
string | object Port label position configuration. It could be a string for setting the port layout type directly with default settings or an object where it's possible to set the layout type and options.
{ position: 'left'}

// or ...

{
    position: {
        name: 'left',
        args: {
            dx: 10
        }
    }
}
  • label.position.name
string Stands for the layout type, match the layout method name defined in joint.layout.PortLabel namespace: name:'left' is implemented as joint.layout.PortLabel.left.
  • label.position.args
object Additional arguments for the layout method. Available properties depends on the layout type. More information could be found in layout.PortLabel section.
  • label.markup
string Custom port label markup. Multiple roots are not allowed. It defaults to <text class="joint-port-label" fill="#000000"/>.
Custom markup

Both port and port label can have custom markup.


    var rect = new joint.shapes.basic.Rect({
        // ...
    });

    rect.addPort({ markup: '<rect width="10" height="10" fill="blue"/>' })
    rect.addPort({ markup: '<rect width="15" height="15" fill="red"/>', label: { markup: '<text fill="#000000"/>' }})

or, it can be set as an default port markup/port label markup on an element model:


    var rect = new joint.shapes.basic.Rect({
        portMarkup: '<rect width="20" height="20" fill="black"/>',
        portLabelMarkup: '<text fill="yellow"/>',
        // ...
    });
dia.Element.prototype.addPort
element.addPort(port, [opt])

Add a single port, where port could be defined as described in section Port interface

dia.Element.prototype.addPorts
element.addPorts(ports, [opt])

Add array of ports. Ports are validated for id duplicities, if there is a id collision, no new ports are added, where port could be defined as describe in section Port interface

dia.Element.prototype.addTo
element.addTo(graph)

Add the element to the graph (an instance of joint.dia.Graph). This is equivalent to calling graph.addCell(element).

dia.Element.prototype.angle
element.angle()

Return the rotation of the element in degrees (0° - 360°).

dia.Element.prototype.attr
element.attr(attrs)

Set SVG attributes (and JointJS special attributes) on subelements. attr can either be an object or string representing a path to a nested attribute. If it is an object, the keys of the attrs object are CSS selectors matching the subelements. The values are objects containing SVG attributes and their values. attrs object will be mixined with attrs property of the element model. This is a convenient way of rewriting only some of the attributes of the subelements. For overwritting all attributes of all subelements, use element.set(attrs).

element.attr({
    rect: { fill: 'blue' },
    text: { fill: 'white', 'font-size': 15 },
    '.myrect2': { fill: 'red' }
});

An alternative call using a string path and a value:

element.attr('text/font-size', 12);
dia.Element.prototype.clone
element.clone(options)

Returns a new instance of the element with identical attributes. If options.deep === true, then all the embedded cells (elements, links) of the element are cloned as well. In this case, the return value is an array of instances rather then a single instance.

dia.Element.prototype.embed
element.embed(cell)

Embed a cell (element or link) into the element. The element then becomes a parent of the embedded cell. When a parent is moved (translated), all cells embedded into that parent will move as well. If links are embedded, their vertices move with the parent. This way both options are available: if a link is not embedded but its source/target elements are and their parent moves, the embedded elements move with the parent but the link vertices stay at the same position. If the link is embedded with its source/target elements, its vertices move as the parent moves.

dia.Element.prototype.findView
element.findView(paper)

Find view (joint.dia.ElementView) for the element model in the paper. This is a shortcut to the equivalent call paper.findViewByModel(element)

dia.Element.prototype.fitEmbeds
element.fitEmbeds([opt])

Resize the element so that it fits all the embedded elements inside it. If opt.deep is true, the resizing will be done recursively for any embedded elements that contain embedded elements themselves. Set opt.padding if you want certain padding on all the parent elements.

dia.Element.prototype.getAncestors
element.getAncestors()

Return an array of all the ancestors of this element starting from the immediate parent all the way up to the most distant ancestor.

dia.Element.prototype.getBBox
element.getBBox()

Returns an element's bounding box represented as a g.rect object (see geometry library).

if (element1.getBBox().intersect(element2.getBBox())) {
    // elements intersect
}
dia.Element.prototype.getEmbeddedCells
element.getEmbeddedCells([opt])

Return an array of all the embedded cells of an element. If all you need is id's of all the embedded cells, use element.get('embeds'). If opt.deep is true, all the deeply embedded cells will be returned. The order in which the cells are returned depends on the search algorithm used. By default, Depth-first search (DFS) algorithm is used. If opt.breadthFirst is true, the Breadth-first search algorithm will be used instead.

dia.Element.prototype.getPort
element.getPort(id)

Returns the port specified by an id. If such a port does not exist the method returns undefined.

dia.Element.prototype.getPortIndex
element.getPortIndex(portId)
Returns the port index in the array of port items.
dia.Element.prototype.getPorts
element.getPorts()

Returns an array of all ports on the element. If there is no port an empty array is returned.

dia.Element.prototype.getPortsPositions
element.getPortsPositions(groupName)

Returns the positions and the angle of all ports in the group, relatively to the element position.

dia.Element.prototype.getTransitions
element.getTransitions()

Return an array of all active transitions (their paths).

dia.Element.prototype.hasPort
element.hasPort(id)

Check if an element contains a port with id. Returns boolean.

dia.Element.prototype.hasPorts
element.hasPorts()

Check if an element has any ports defined. Returns boolean.

dia.Element.prototype.isElement
element.isElement()

Always returns true. The reason the method is here is that both joint.dia.Element and joint.dia.Link inherit from joint.dia.Cell. This method is useful if you don't know what the cell is. Calling cell.isElement() is equivalent to cell instanceof joint.dia.Element. Example:

var cell = graph.getCell(myId)
if (cell.isElement()) {
    // Do something if the cell is an element.
}
dia.Element.prototype.isEmbeddedIn
element.isEmbeddedIn(element [, opt])

Return true if the element is embedded in another element element. If opt.deep is false, only direct parentage will be checked. opt.deep is true by default.

dia.Element.prototype.portProp
element.portProp(portId, path, [value])

Set properties, possibly nested, on the element port. This is an equivalent of the attr() method but this time for custom data properties.

element.portProp('port-id', 'attrs/circle/fill', 'red');
element.portProp('port-id', 'attrs/circle/fill');  // 'red'

element.portProp('port-id', 'attrs/circle', { r: 10, stroke: 'green' });
element.portProp('port-id', 'attrs/circle'); // { r: 10, stroke: 'green', fill: 'red' }
dia.Element.prototype.position
element.position(x, y, [opt])

Set the element position to x and y coordinates. This is almost equivalent to element.set('position', { x: x, y: y }, opt). However, this method provides some additional functionality. If you set opt.parentRelative flag to true, the x and y coordinates will be treated relatively to the parent element of this element. If position() is called without arguments, it returns the current position. If position({ parentRealtive: true }) is called without x and y coordinates and with the parentRelative flag set to true, the method returns the current position of the element relative to its parent. Setting opt.deep to true will position not only the element but also all its descendants keeping the original distances from a child to the element origin.

el1.position(100, 100);
el1.embed(el2);
el2.position(10, 10, { parentRelative: true });
el2.position() // --> 110@110
el1.position(200,200, { deep: true });
el2.position() // --> 210@210
dia.Element.prototype.prop
element.prop(properties)

Set properties, possibly nested, on the element model. This is an equivalent of the attr() method but this time for custom data properties.

element.prop('name/first', 'John')
element.prop('name/first')  // 'John'
element.prop({ name: { first: 'John' } })
// Nested arrays are supported too:
element.prop('mylist/0/data/0/value', 50)
element.prop({ mylist: [ { data: [ { value: 50 } ] } ] })
dia.Element.prototype.remove
element.remove(options)

Remove the element from the graph. All its embedded elements will get removed too and the element gets unembedded from its parent element. By default, all the associated links are removed too. To suppress this behaviour, set options.disconnectLinks === true. In this case, all the associated links get disconnected from this element rather then removed completely from the graph.

dia.Element.prototype.removeAttr
element.removeAttr(path, [options])

Remove a previously set attribute from the element. path can either be a string that specifies the path to the, possibly nested, attribute to be removed or an array of more paths. The associated element view makes sure the element gets re-rendered properly. If options is passed, it can contain data that is passed over to the event listeners for the change:attrs event triggered on the element itself and also on the graph the element is in.

dia.Element.prototype.removePort
element.removePort(port, [opt])

Remove a port from an element, where port is a port object, or portId.

dia.Element.prototype.resize
element.resize(width, height [, opt])

Resize an element in place so that the "scalable" group has width width and height height. In place in this case means that the top-left corner of the element stays at the same position after resizing. In other words, the element is streched to the bottom/right (by default). To change the direction of resizing, set opt.direction to one of 'left', 'right', 'top', 'bottom', 'top-right', 'top-left', 'bottom-left' or 'bottom-right' (the default).

There is a difference between a classical scale and resize operations. resize doesn't actually scale the whole SVG <g> element grouping all its subelements. It only scales subelements of the <g class"scalable"/> group. This is very useful and brings a lot of flexibility in defining which subelements should be scaled and which not. Imagine a simple rectangle element with text inside. Usually, when we resize the whole element, we expect the rectangle to get scaled while the text should stay the same size, only its position should be adjusted so that the text stays in the center of the rectangle. This can be easilly achieved by adding the <rect/> element to the <g class"scalable"/> group in the markup and positioning the text subelement relatively to the <rect /> element: <text ref-x=".5" ref-y=".5" ref="rect" />. Note that neither of ref-x, ref-y and ref attributes is an SVG standard attribute. These are special attributes introduced by JointJS. More on these in the section on Special attributes.

dia.Element.prototype.rotate
element.rotate(deg, [absolute, origin, opt])

Rotate an element by deg degrees around its center. If the optional absolute parameter is true, the deg will be considered an absolute angle, not an addition to the previous angle. If origin is passed in the form of an object with x and y properties, then this point will be used as the origin for the rotation transformation.

dia.Element.prototype.scale
element.scale(sx, sy, origin[, opt])

Scales the element's position and size relative to the given origin.

dia.Element.prototype.stopTransitions
element.stopTransitions([path])

Stops all running transitions. If parameter path is provided, it will stop only transitions specified by this path.

dia.Element.prototype.toBack
element.toBack([opt])

Move the element so it is behind all other cells (elements/links). If opt.deep is true, all the embedded cells of this element will get higher z index than that of this element in a Breadth-first search (BFS) fashion. This is especially useful in hierarchical diagrams where if you want to send an element to the back, you don't want its children (embedded cells) to be hidden behind that element.

dia.Element.prototype.toFront
element.toFront([opt])

Move the element so it is on top of all other cells (element/links). If opt.deep is true, all the embedded cells of this element will get higher z index than that of this element in a Breadth-first search (BFS) fashion. This is especially useful in hierarchical diagrams where if you want to send an element to the front, you don't want its children (embedded cells) to be hidden behind that element.

All elements have a z property defining their z-level in the graph. This z property can even be set directly by element.set('z', 123). This change will be automatically handled by the joint.dia.Paper object associated with the joint.dia.Graph object this element is part of and all the SVG elements will get resorted so that their position in the DOM reflects the z level.

dia.Element.prototype.toJSON
element.toJSON()

Return a copy of the element's attributes for JSON serialization. This can be used for persistance or serialization. Note that this method doesn't return a JSON string but rather an object that can be then serialized to JSON with JSON.stringify().

dia.Element.prototype.transition
element.transition(path, value [, opt])

Allows to change the element's property gradually over a period of time. This method lets you specify what property to change (path), when the transition will start (options.delay), how long the transition will last (options.duration), how the transition will run (options.timingFunction), and how to interpolate the property value (options.valueFunction).

element.transition('position/x', 250, {
    delay: 100,
    duration: 500,
    timingFunction: function(t) { return t*t; },
    valueFunction: function(a, b) { return function(t) { return a + (b - a) * t }}
});
// will start changing the element's x-coordinate in 100ms, for period of 500ms.

JointJS comes pre-built with some common timing and interpolating functions. The timing functions are defined in the joint.util.timing namespace and the interpolating functions in the joint.util.interpolate namespace. The predefined timing functions are:

  • linear
  • quad
  • cubic
  • inout
  • exponential
  • bounce

and the predefined interpolating functions are:

  • number
  • object
  • hexColor
  • unit

element.transition('attrs/text/font-size', '1em', { 
    valueFunction: joint.util.interpolate.unit,
    timingFunction: joint.util.timing.bounce
});
// will start changing the current font size value to 1em in the bounce fashion.
dia.Element.prototype.translate
element.translate(tx, [ty], [opt])

Translate an element by tx pixels in x axis and ty pixels in y axis. ty is optional in which case the translation in y axis will be considered zero. The optional options object opt can be used to pass additional parameters to the event handlers listening on 'change:position' events. opt.transition can be used to initiate an animated transition rather than a sudden move of the element. See joint.dia.Element:transition for more info on transitions. If opt.restrictedArea is set, the translation of the element will be restricted to that area only. The restrictedArea is an object of the form { x: Number, y: Number, width: Number, height: Number }. This is useful, e.g. if you want to restrict the translation of an embedded element within its parent. The only thing you have to do in this case is to pass the bounding box of the parent element to the restrictedArea option:

myElement.translate(50, 50, { restrictedArea: graph.getCell(myElement.get('parent')).getBBox() })

The code above makes sure that the element myElement never crosses the bounding box of its parent element. note that this also works if the element myElement has other embedded elements. In other words, the bounding box of the myElement that is used to calculate the restriction is the total bounding box, including all its children (in case they are sticking out).

dia.Element.prototype.unembed
element.unembed(cell)

Free up an embedded cell from its parent element.

dia.ElementView

The view for the joint.dia.Element model. It inherits from joint.dia.CellView and is responsible for:

  • Rendering an element inside of a paper
  • Handling the element's pointer events
  • Provides various methods for working with the element (visually)

To find the view associated with a specific element (model), use the findViewByModel method of the paper.

var elementView = paper.findViewByModel(element);
dia.ElementView.prototype.getBBox
elementView.getBBox([opt])

Return a bounding box for an element view. If opt.useModelGeometry option is set to true, the resulting bounding box will be calculated based on the element model dimensions (so that SVG sub elements sticking out of the element will be excluded). The difference from dia.Element.prototype.getBBox is that in this case, the bounding box will be adjusted based on the joint.dia.Paper translate and scale.

dia.ElementView.prototype.getNodeBBox
elementView.getNodeBBox(magnet)

Return the bounding box of the SVGElement provided as magnet (element/subelement/port of this element view).

dia.ElementView.prototype.getNodeUnrotatedBBox
elementView.getNodeUnrotatedBBox(magnet)

Return the unrotated bounding box of the SVGElement provided as magnet (element/subelement/port of this element view).

dia.Graph.constructor

joint.dia.Graph is the model holding all the cells (elements and links) of the diagram. It's a Backbone model. The collection of all the cells is stored in the property cells.

The graph is a powerful data model behind all JointJS diagrams. It not only provides an efficient storage for directed graphs but also offers useful algorithms for traversing the graphs.

Additionally, the graph accepts an option object in its constructor function that can contain the cellNamespace option. This option can be used to change the default behavior of JointJS which by default reads cell model definitions from the joint.shapes namespace. For example, if a cell is of type 'myshapes.MyElement', then the graph looks up joint.shapes.myshapes.MyElement model when deserializing a graph from the JSON format. If the graph is instantiated as e.g. var graph = new joint.dia.Graph({}, { cellNamespace: myShapesNamespace }), then the graph will read the model definition from the myShapesNamespace.myshapes.MyElement object instead. This is useful in situations where you don't want to - for any reason - use the joint.shapes namespace for defining your own custom shapes. This option is often used in combination with the cellNamespaceView option on the joint.dia.Paper object.

dia.Graph.events

The following list contains events that you can react on:

  • change - generic event triggered for any change in the graph
  • add - triggered when a new cell is added to the graph
  • remove - triggered when a cell is removed from the graph
  • Moreover, all the events that are triggered on elements or links are propagated to the graph as well.
graph.on('add', function(cell) { 
    alert('New cell with id ' + cell.id + ' added to the graph.') 
})

dia.Graph.JSON

The JointJS graph JSON representation has the following format:

{
    cells: [// Array of cells (ie. links and elements).
        {
            id: '3d90f661-fe5f-45dc-a938-bca137691eeb',// Some randomly generated UUID.
            type: 'basic.Rect',
            attrs: {
                'stroke': '#000'
            },
            position: {
                x: 0,
                y: 50
            },
            angle: 90,
            size: {
                width: 100,
                height: 50
            },
            z: 2,
            embeds: [
                '0c6bf4f1-d5db-4058-9e85-f2d6c74a7a30',
                'cdbfe073-b160-4e8f-a9a0-22853f29cc06'
            ],
            parent: '31f348fe-f5c6-4438-964e-9fc9273c02cb'
            // ... and some other, maybe custom, data properties
        }
    ]
}
dia.Graph.prototype.addCell
graph.addCell(cell)

Add a new cell to the graph. If cell is an array, all the cells in the array will be added to the graph.

var rect = new joint.shapes.basic.Rect({ 
    position: { x: 100, y: 100 },
    size: { width: 70, height: 30 },
    attrs: { text: { text: 'my rectangle' } }
})
var rect2 = rect.clone()
var link = new joint.dia.Link({ source: { id: rect.id }, target: { id: rect2.id }  });
var graph = new joint.dia.Graph
graph.addCell(rect).addCell(rect2).addCell(link)
dia.Graph.prototype.addCells
graph.addCells(cells[, opt])
graph.addCells(cell, cell, ..[, opt])

Add new cells to the graph. This is just a convenience method that wraps the addCell method.

dia.Graph.prototype.bfs
graph.bfs(element, iteratee [, opt])

Traverse the graph using the Breadth-first search algorithm starting at element (note the element itself will be visited too). iteratee is a function of the form function(element, distance) {} that will be called with the currently visited element and distance of that element from the root element of the search (the element passed to bfs()). If iteratee explicitely returns false, the search stops.

The following image shows the order in which elements are traversed in the graph:

graph BFS algorithm

Note that the bfs() algorithm is not only capable of traversing tree graphs but it can traverse any directed graph too.

It is smart enough not to traverse an element that was already visited.

If opt.inbound is true, reverse the search direction (it's like reversing all the link directions, i.e. swaping their source and target).

If opt.outbound is true, search follows the link directions. Calling bfs() with opt.outbound set to true is the most common case (graph is traversed following the direction of links).

If none of opt.inbound and opt.outbound are used or both options are set to true, the graph is traversed in both directions (very rare use case).

If opt.deep is true, the traversal takes into account embedded elements too. This option has the usual meaning as in other methods were deep option is used. For example, in a hierarchy A (top level element), A1 (embedded in A), B (top level element), where A is not directly connected to B but its embedded element is (there is a link from A1 ----> B), bfs(A)would not visit B but bfs(A, function() {}, { deep: true }) would.

dia.Graph.prototype.clear
graph.clear([options)

Remove all the cells from the graph. options object can optionally contain additional data that is passed overto the event listeners of the graph cells remove event.

dia.Graph.prototype.cloneCells
graph.cloneCells(cells)

Clone all the cells (elements and/or links) from the cells array and return an object that maps the original cell ID to the clone (i.e. an object of the form { [original cell ID]: [clone] }). The reason why this object is returned instead of an array of clones is that it is very useful to know which object the clone was created for.
The number of clones returned equals cells.length. This function does not simply clone all the cells but it also reconstructs all the source/target and parent/embed references within cells. This is very useful. For example, for a graph A --- L ---> B, cloneCells([A, L, B]) returns { A.id: A2, L.id: L2, B.id: B2 } resulting in a graph A2 --- L2 ---> B2, i.e. the source and target of the link L2 is changed to point to A2 and B2 (in contrast to just looping over cells and calling cell.clone() on each item).

dia.Graph.prototype.cloneSubgraph
graph.cloneSubgraph(cells [, opt])

Clone the whole subgraph, including all the connected links whose source/target is in the subgraph. This is equivalent to calling graph.cloneCells(graph.getSubgraph(cells)).
If opt.deep is true, take into account embedded cells of the subgraph cells.
Return an object of the form { [original cell ID]: [clone] }.

dia.Graph.prototype.dfs
graph.dfs(element, iteratee [, opt])

Traverse the graph using the Depth-first search algorithm starting at element (note the element itself will be visited too). iterate is a function of the form function(element, distance) {} that will be called with the currently visited element and distance of that element from the root element of the search (the element passed to dfs()). If iteratee explicitely returns false, the search stops.

The following image shows the order in which elements are traversed in the graph:

graph DFS algorithm

Note that the dfs() algorithm is not only capable of traversing tree graphs but it can traverse any directed graph too. It is smart enough not to traverse an element that was already visited.

If opt.inbound is true, reverse the search direction (it's like reversing all the link directions, i.e. swaping their source and target).

If opt.outbound is true, search follows the link directions. Calling dfs() with opt.outbound set to true is the most common case (graph is traversed following the direction of links).

If none of opt.inbound and opt.outbound are used or both options are set to true, the graph is traversed in both directions (very rare use case).

If opt.deep is true, the traversal takes into account embedded elements too. This option has the usual meaning as in other methods were deep option is used. For example, in a hierarchy A (top level element), A1 (embedded in A), B (top level element), where A is not directly connected to B but its embedded element is (there is a link from A1 ----> B), dfs(A) would not visit B but dfs(A, function() {}, { deep: true }) would.

dia.Graph.prototype.findModelsFromPoint
graph.findModelsFromPoint(point)

Find elements (instance of joint.dia.Element) under a certain point in the graph. point is an object with x and y properties. Returns an array of elements whose bounding box contains point. Note that there can be more then one element as elements might overlap.

dia.Graph.prototype.findModelsInArea
graph.findModelsInArea(rect)

Find elements (instance of joint.dia.Element) in a certain area in the graph. rect is an object with x, y, width and height properties. Returns an array of elements whose bounding box top/left coordinate falls into the rect rectangle.

dia.Graph.prototype.findModelsUnderElement
graph.findModelsUnderElement(element [, opt])

Find all the elements (instances of joint.dia.Element) that are located below element. opt.searchBy parameter optionally determines what it means for an element to be below another element. Possible values are 'bbox' (default), 'center', 'origin', 'corner', 'topRight', and 'bottomLeft'.

dia.Graph.prototype.fromJSON
graph.fromJSON(jsonObject, [options])

Load a graph from a JSON object (not string). Used in conjunction with the graph.toJSON() function.

The options object may contain additional data that is passed over to graph change event listeners.

Note that this method does not expect a JSON string but rather an object in the JSON format. Use JSON.parse(jsonString) if you need to convert a JSON string into the object form:

graph.fromJSON(JSON.parse(jsonString));

Example of storing stringified JSON objects:

var jsonString = JSON.stringify(graph.toJSON());
// ... send jsonString to the server
// store jsonString to localStorage or do whatever you want
// later on ...
graph.fromJSON(JSON.parse(jsonString));

Example of storing JSON objects directly:

var jsonObject = graph.toJSON();
// ... send jsonObject to the server
// store jsonObject (e.g. in a non-relational database)
// later on ...
graph.fromJSON(jsonObject)
dia.Graph.prototype.getBBox
graph.getBBox(cells[, opt])

Returns the bounding box that surrounds all the given cells. Links are ignored. An example:

var bbox = graph.getBBox(graph.getElements());
// { x: Number, y: Number, width: Number, height: Number }
dia.Graph.prototype.getCell
graph.getCell(id)

Get a cell from the graph by its id.

dia.Graph.prototype.getCells
graph.getCells()

Get all the elements and links in the graph.

dia.Graph.prototype.getCommonAncestor
graph.getCommonAncestor(cells...)

Return the common ancestor of all the cells passed as arguments. For example, if an element B is embedded in an element A and an element C is also embedded in the element A, graph.getCommonAncestor(B, C) returns the element A. This also works on an arbitrary deep hierarchy.

dia.Graph.prototype.getElements
graph.getElements()

Get all the elements in the graph (i.e. omit links).

dia.Graph.prototype.getFirstCell
graph.getFirstCell()

Get the first cell (element or link) in the graph. The first cell is defined as the cell with the lowest z property (the cell most in the back, see the Presentation section of joint.dia.Element).

dia.Graph.prototype.getLastCell
graph.getLastCell()

Get the last cell (element or link) in the graph. The last cell is defined as the cell with the highest z property (the cell most in the front, see the Presentation section of joint.dia.Element).

dia.Graph.prototype.getNeighbors
graph.getNeighbors(element [, opt])

Get all the neighbors of element in the graph. Neighbors are all the elements connected to element via either an inbound or an outbound link. If opt.inbound is true, only inbound neighbords (all neighbors connected with a link who's target is the element) will be returned. Similarly, if opt.outbound is true, only outbound neighbors will be returned. If opt.deep is true, return also all the neighbors of all the elements embedded inside element.

dia.Graph.prototype.getPredecessors
graph.getPredecessors(element [, opt])

Return an array of all the predecessors of element. By default, Depth-first search algorithm is used (important for the order of returned elements).
If opt.breadthFirst is set to true, use Breadth-first search algorithm instead.
If opt.deep is set to true, take into account embedded elements too (see dfs() for details).

dia.Graph.prototype.getSinks
graph.getSinks()

Return an array of all the leafs of the graph. Time complexity: O(|V|).

dia.Graph.prototype.getSources
graph.getSources()

Return an array of all the roots of the graph. Time complexity: O(|V|).

dia.Graph.prototype.getSubgraph
graph.getSubgraph(cells [, opt])

Return an array of cells that result from finding elements/links that are connected to any of the cells in the cells array. This function loops over cells and if the current cell is a link, it collects its source/target elements; if it is an element, it collects its incoming and outgoing links if both the link ends (source/target) are in the cells array. For example, for a single element, the result is that very same element. For two elements connected with a link: A --- L ---> B, the result of getSubgraph([A, B]) is [A, L, B] and the result of getSubgraph([L]) is also [A, L, B].
If opt.deep is true take into account all the embedded cells too when finding neighboring links/elements.

dia.Graph.prototype.getSuccessors
graph.getSuccessors(element [, opt])

Return an array of all the successors of element. By default, Depth-first search algorithm is used (important for the order of returned elements).
If opt.breadthFirst is set to true, use Breadth-first search algorithm instead.
If opt.deep is set to true, take into account embedded elements too (see dfs() for details).

dia.Graph.prototype.isNeighbor
graph.isNeighbor(elementA, elementB [, opt])

Return true if elementB is a neighbor of elementA. If opt.deep is set to true, take into account embedded elements.
If opt.outbound is set to true, return true only if elementB is a successing neighbor of elementA.
Similarly, if opt.inbound is set to true, return true only if elementB is a preceeding neighbor of elementA.

dia.Graph.prototype.isPredecessor
graph.isPredecessor(elementA, elementB)

Return true if elementB is a predecessor of elementA.

dia.Graph.prototype.isSink
graph.isSink(element)

Return true if element is a leaf, i.e. there is no link coming out of the element. Time complexity: O(1).

dia.Graph.prototype.isSource
graph.isSource(element)

Return true if element is a root, i.e. there is no link that targets the element. Time complexity: O(1).

dia.Graph.prototype.isSuccessor
graph.isSuccessor(elementA, elementB)

Return true if elementB is a successor of elementA.

dia.Graph.prototype.maxZIndex
graph.maxZIndex()

Get the highest Z value in the graph (the value of the cell on front).

dia.Graph.prototype.minZIndex
graph.minZIndex()

Get the lowest Z value in the graph (the value of the cell on the back).

dia.Graph.prototype.removeCells
graph.removeCells(cells[, opt])
graph.removeCells(cell, cell, ..[, opt])

Removes the given cells from the graph.

dia.Graph.prototype.resetCells
graph.resetCells(cells[, opt])
graph.resetCells(cell, cell, ..[, opt])

Reset cells in the graph. Update all the cells in the graph in one bulk. This is a more efficient method of adding cells to the graph if you ou want to replace all the cells in one go. options object can optionally contain additional data that is passed over to the event listeners of the graph reset event.

dia.Graph.prototype.search
graph.search(element, iteratee [, opt])

Traverse the graph starting at element following links. This function is a wrapper around dfs() or bfs(). By default, it uses dfs(). If opt.breadthFirst is set to true, bfs() will be used instead.

dia.Graph.prototype.toJSON
graph.toJSON()

Return an object representation of the graph, which can be used for persistence or serialization. Use the graph.fromJSON() function to load a previously converted graph.

Note that this method does not return a JSON string but rather an object that can then be serialized to JSON with JSON.stringify(jsonObject):

var jsonString = JSON.stringify(graph.toJSON());
dia.Graph.prototype.translate
graph.translate(tx, ty [, opt])

Translate all cells in the graph by tx and ty pixels. It uses the dia.Element.translate() and dia.Link.translate() methods internally.

dia.LinkView

The view for the joint.dia.Link model. It inherits from joint.dia.CellView and is responsible for:

  • Rendering a link inside a paper
  • Handling the link's pointer events
  • Providing various methods for working with the link (visually)

To find the view associated with a specific link model, use the paper.findViewByModel() method:

var linkView = paper.findViewByModel(link);

Custom LinkView

It is possible to use a custom default link view for all your links in a paper. This can be set up via the linkView option on the paper object. Several options in joint.dia.LinkView may be overridden in a custom LinkView:

  • shortLinkLength - if link is shorter than the length specified, the size of link tools is scaled down by half. Defaults to 105.
  • doubleLinkTools - render link tools on both ends of the link (only if the link is longer than longLinkLength). Defaults to false.
  • longLinkLength - if length is longer than the length specified and doubleLinkTools: true, render link tools on both ends of the link. Defaults to 155.
  • linkToolsOffset - the offset of link tools from the beginning of the link. Defaults to 40.
  • doubleLinkToolsOffset - the offset of duplicate link tools from the end of the link, if length is longer than longLinkLength and doubleLinkTools: true. Defaults to 65.

A custom LinkView type may also override default LinkView event handlers, or provide new ones. It may be necessary to modify the interactive paper option to prevent interference from builtin event handlers (most notably vertexAdd which listens for pointerdown events).

Example:

var CustomLinkView = joint.dia.LinkView.extend({
    // custom interactions:
    pointerdblclick: function(evt, x, y) {
        this.addVertex(x, y);
    },
    contextmenu: function(evt, x, y) {
        this.addLabel(x, y);
    },

    // custom options:
    options: joint.util.defaults({
        doubleLinkTools: true,
    }, joint.dia.LinkView.prototype.options)
});

var paper = new joint.dia.Paper({
    //...
    linkView: CustomLinkView,
    interactive: { vertexAdd: false } // disable default vertexAdd interaction
});
dia.LinkView.prototype.addLabel
linkView.addLabel(x, y [, opt])

Add a new default label to the link at the coordinates provided. If you need to add a label with custom markup or properties, use the link.addLabel() function instead.

This method uses the linkView.getLabelPosition() function to determine the new label's position. By default, position.distance is recorded relative to connection length (as a number in the [0,1] range), and position.offset is set relative to the connection (as a number). This behavior may be changed by providing an opt object with some of the accepted boolean flags:

  • absoluteDistance: true records distance absolutely (as distance from beginning of link)
  • reverseDistance: true switches distance to be calculated from end of link, if absoluteDistance
  • absoluteOffset: true records offset absolutely (as x and y from connection)

The opt object passed to the label is recorded as label.position.args. The label uses these options during subsequent labelMove interactions.

This function is useful within custom linkView event listener definitions:

var CustomLinkView = joint.dia.LinkView.extend({
    contextmenu: function(evt, x, y) {
        this.addLabel(x, y, {
            absoluteDistance: true,
            reverseDistance: true,
            absoluteOffset: true
        });
    }
});

var paper = new joint.dia.Paper({
    // ...
    linkView: CustomLinkView,
    interactive: { vertexAdd: false } // disable default vertexAdd interaction
});
dia.LinkView.prototype.addTools
linkView.addTools(toolsView)

Add the provided toolsView (of the joint.dia.ToolsView type) to the link view.

Adding a tools view to a link view is the last (third) step in the process of setting up link tools on a link view:

// 1) creating link tools
var verticesTool = new joint.linkTools.Vertices();
var segmentsTool = new joint.linkTools.Segments();
var boundaryTool = new joint.linkTools.Boundary();

// 2) creating a tools view
var toolsView = new joint.dia.ToolsView({
    name: 'basic-tools',
    tools: [verticesTool, segmentsTool, boundaryTool]
});

// 3) attaching to a link view
var linkView = link.findView(paper);
linkView.addTools(toolsView);

Every link view we want to attach to requires its own tools view object (ToolsView objects are automatically reassigned to the last link view they are added to). Similarly, every tools view we create requires its own set of tools (ToolView objects are automatically reassigned to the last toolsView.tools array they were made part of).

The link tools are added in the visible state. Use the linkView.hideTools function if this behavior is not desirable (e.g. if you want the link tools to appear in response to user interaction). Example:

linkView.addTools(toolsView);
linkView.hideTools();

paper.on('link:mouseenter', function(linkView) {
    linkView.showTools();
});

paper.on('link:mouseleave', function(linkView) {
    linkView.hideTools();
});
dia.LinkView.prototype.addVertex
linkView.addVertex(x, y)

Add a new default vertex to the link at the coordinates provided, and let the linkView automatically determine the index of the new vertex in the vertices array. If you need to add the vertex at a custom index, use the link.addVertex() function instead.

This method uses the linkView.getVertexIndex() function to determine the index of the new vertex in the vertices array. The linkView checks the distance of vertices in the link.vertices array from the beginning of path and compares it to the distance of the added vertex. The new vertex is inserted before the first farther vertex in the vertices array.

This function is useful within custom linkView event listener definitions. The following example adds a new vertex on a double click event, instead of a pointerdown event (which is the default behavior):

var CustomLinkView = joint.dia.LinkView.extend({
    pointerdblclick: function(evt, x, y) {
        this.addVertex(x, y);
    }
});

var paper = new joint.dia.Paper({
    // ...
    linkView: CustomLinkView,
    interactive: { vertexAdd: false } // disable default vertexAdd interaction
});
dia.LinkView.prototype.getBBox
linkView.getBBox()

Return the bounding box of the linkView.

dia.LinkView.prototype.getClosestPoint
linkView.getClosestPoint(point)

Return the point on the connection that lies closest to point.

dia.LinkView.prototype.getClosestPointLength
linkView.getClosestPointLength(point)

Return the length of the connection up to the point that lies closest to point.

dia.LinkView.prototype.getClosestPointRatio
linkView.getClosestPointRatio(point)

Return the ratio (normalized length) of the connection up to the point that lies closest to point. The returned value lies in the interval [0,1] (inclusive).

dia.LinkView.prototype.getConnection
linkView.getConnection()

Return a geometric representation of the connection (instance of g.Path).

dia.LinkView.prototype.getConnectionLength
linkView.getConnectionLength()

Return a cached total length of the connection in pixels.

dia.LinkView.prototype.getConnectionSubdivisions
linkView.getConnectionSubdivisions()

Return a cached array of segment subdivision arrays of the connection. (See g.Path.prototype.getSegmentSubdivisons() documentation for more information.)

dia.LinkView.prototype.getLabelCoordinates
linkView.getLabelCoordinates(labelPosition)

Return the x and y coordinates based on the provided labelPosition object.

See link.label() documentation for more information about the position object.

An object in the format { x: number, y: number } is returned.

dia.LinkView.prototype.getLabelPosition
linkView.getLabelPosition(x, y [, opt])

Return a label position object based on the x and y coordinates provided.

The function translates the provided coordinates into an object with two fields:

  • distance - the distance (following the line) of the point on the line that is closest to point x,y.
  • offset - the distance between the closest point and the point x,y.

By default, position.distance is set relative to connection length (as a number in the [0,1] range that records the length ratio), and position.offset is set relative to the connection (as a number recording the perpendicular distance). The user may change this behavior by providing an opt object with some of the following accepted boolean flags:

  • absoluteDistance: true - record distance absolutely (as absolute distance from beginning of link, a positive number).
  • reverseDistance: true - if absoluteDistance: true, record distance absolutely from end of link (as a negative number).
  • absoluteOffset: true - record offset absolutely (as x and y distance from closest point).

Please note that if absoluteOffset is not set (i.e. the default option), label can only be placed/moved in the area that is reachable by lines perpendicular to the link (that is, the label cannot be moved beyond link endpoints).

The opt object passed to the label is recorded as label.position.args. The label uses these options during subsequent labelMove interactions.

An object in the following format is returned:

{
    distance: number,
    offset: number | { x: number, y: number },
    args?: {
        absoluteDistance?: boolean,
        reverseDistance?: boolean,
        absoluteOffset?: boolean
    }
}

See link.label() documentation for more information about the position object.

This function can be used to add a custom label to the link.labels array, in situations when the linkView.addLabel() function is not sufficient. For example:

var CustomLinkView = joint.dia.LinkView.extend({
    contextmenu: function(evt, x, y) {
        var idx = -1; // add at end of `labels`
        var label = {
            markup: '<g class="label"><circle /><path /></g>',
            position: this.getLabelPosition(x, y, { absoluteOffset: true }),
            attrs: {
                circle: {
                    r: 15,
                    fill: 'lightgray',
                    stroke: 'black',
                    strokeWidth: 2
                },
                path: {
                    d: 'M 0 -15 0 -35 20 -35',
                    stroke: 'black',
                    strokeWidth: 2,
                    fill: 'none'
                }
            }
        }
        this.model.addLabel(idx, label);
    }
});

var paper = new joint.dia.Paper({
    //...
    linkView: CustomLinkView,
    interactive: { vertexAdd: false }
});
dia.LinkView.prototype.getPointAtLength
linkView.getPointAtLength(length)

Return the point on the path that lies length away from the beginning of the connection.

dia.LinkView.prototype.getPointAtRatio
linkView.getPointAtRatio(ratio)

Return the point on the path that lies ratio (normalized length) away from the beginning of the connection.

dia.LinkView.prototype.getSerializedConnection
linkView.getSerializedConnection()

Return a cached path data of the connection (the value of the 'd' SVGPathElement attribute).

dia.LinkView.prototype.getTangentAtLength
linkView.getTangentAtLength(length)

Return a line tangent to the path at point that lies length away from the beginning of the connection.

dia.LinkView.prototype.getTangentAtRatio
linkView.getTangentAtRatio(ratio)

Return a line tangent to the path at point that lies ratio (normalized length) away from the beginning of the connection.

dia.LinkView.prototype.getVertexIndex
linkView.getVertexIndex(x, y)

Return the vertices array index at which to insert a new vertex with the provided x and y coordinates.

The linkView finds the point on the connection that lies closest to the point x,y. Then, the linkView iterates over the vertices in the link.vertices array until one is found that lies farther than the identified closest point. The index of the farther point is returned.

The returned index can be used as the first argument of the link.addVertex function.

dia.LinkView.prototype.hasTools
linkView.hasTools()

Return true if this link view has a tools view attached.

linkView.hasTools(name)

Return true if this link view has a tools view of the provided name attached.

dia.LinkView.prototype.hideTools
linkView.hideTools()

Hide all tools attached to this link view.

dia.LinkView.prototype.removeRedundantLinearVertices
linkView.removeRedundantLinearVertices([opt])

Remove any redundant vertices from the model's vertices array. Return the number of removed vertices.

A vertex is considered redundant if it lies on the straight line formed by the vertex that immediately precedes it and the vertex that immediately follows it. (Intuitively speaking, a vertex is considered redundant if its removal from the link does not change the shape of the link.)

dia.LinkView.prototype.removeTools
linkView.removeTools()

Remove the tools view attached to this link view.

dia.LinkView.prototype.sendToken
linkView.sendToken(token [, opt, callback])

Send a token along the link. token is an SVG element (or Vectorizer element) that will be animated along the link path for opt.duration milliseconds (default is 1000ms). The callback function will be called once the token reaches the end of the link path.

opt.direction specifies whether the animation should be played forwards ('normal' - from the link source to target, the default) or backwards ('reverse').

Use opt.connection to specify the SVGPathElement for the token to follow. It expects a string selector, e.g. '.connection'.

// Send an SVG circle token along the link.
var vCircle = V('circle', { r: 7, fill: 'green' });
link.findView(paper).sendToken(vCircle, { duration: 500, direction: 'reverse' }, function() {
  console.log('animation end');
});

Note that in the code above, we use the Vectorizer mini-library to create the SVG circle element.

See the Petri Net simulator demo for a full working example.

dia.LinkView.prototype.showTools
linkView.showTools()

Show all tools attached to this link view.

dia.LinkView.prototype.sourceAnchor
linkView.sourceAnchor

A prototype variable. Contains a g.Point that records the position of the source anchor of the link, as determined by the anchor function specified on the link's source.

dia.LinkView.prototype.sourceBBox
linkView.sourceBBox

A prototype variable. Contains a g.Rect that records the position and dimensions of the bounding box of the source magnet (element/subelement/port), as determined by the link's source definition.

If the source is defined as a point, a g.Rect is returned that records the position of the point and has the dimensions (1,1).

dia.LinkView.prototype.sourcePoint
linkView.sourcePoint

A prototype variable. Contains a g.Point that records the position of the source connection point of the link, as determined by the connection point function specified on the link's source.

dia.LinkView.prototype.targetAnchor
linkView.targetAnchor

A prototype variable. Contains a g.Point that records the position of the target anchor of the link, as determined by the anchor function specified on the link's target.

dia.LinkView.prototype.targetBBox
linkView.targetBBox

A prototype variable. Contains a g.Rect that records the position and dimensions of the bounding box of the target magnet (element/subelement/port), as determined by the link's target definition.

If the target is defined as a point, a g.Rect is returned that records the position of the point and has the dimensions (1,1).

dia.LinkView.prototype.targetPoint
linkView.targetPoint

A prototype variable. Contains a g.Point that records the position of the target connection point of the link, as determined by the connection point function specified on the link's target.

dia.Paper.constructor

joint.dia.Paper is the view for the joint.dia.Graph model. It inherits from Backbone View. Accepts an options object in its constructor with numerous settings.

When a paper is associated with a graph, the paper makes sure that all the cells added to the graph are automatically rendered.

var graph = new joint.dia.Graph
var paper = new joint.dia.Paper({
    el: $('#paper'),
    width: 600,
    height: 400,
    gridSize: 10,
    model: graph
});

var rect = new joint.shapes.basic.Rect({
    position: { x: 50, y: 70 },
    size: { width: 100, height: 40 }
});

graph.addCell(rect);

Paper automatically handles this change and renders the rectangle to the SVG document that it internally holds.

dia.Paper.events

The following list contains events that you can react on in a paper:

pointerdblclick

Triggered when pointer is double-clicked on a target (a dblclick event is detected).

The callback function is passed cellView, evt, x and y as arguments.

cell:pointerdblclick Triggered when pointer is double-clicked on a cell.
link:pointerdblclick Triggered when pointer is double-clicked on a link.
element:pointerdblclick Triggered when pointer is double-clicked on an element.
blank:pointerdblclick

Triggered when pointer is double-clicked on the paper outside any cell.

The callback function is passed evt, x and y as arguments.

pointerclick

Triggered when pointer is clicked on a target without pointer movement (a click or touchend event is detected). Occurs alongside pointerdown and pointerup events.

The callback function is passed cellView, evt, x and y as arguments.

cell:pointerclick Triggered when pointer is clicked on a cell.
link:pointerclick Triggered when pointer is clicked on a link.
element:pointerclick Triggered when pointer is clicked on an element.
blank:pointerclick

Triggered when pointer is clicked on the paper outside any cell.

The callback function is passed evt, x and y as arguments.

contextmenu

Triggered when pointer is right-clicked on a target (a contextmenu event is detected).

The callback function is passed cellView, evt, x and y as arguments.

cell:contextmenu Triggered when pointer is right-clicked on a cell.
link:contextmenu Triggered when pointer is right-clicked on a link.
element:contextmenu Triggered when pointer is right-clicked on an element.
blank:contextmenu

Triggered when pointer is right-clicked on the paper outside any cell.

The callback function is passed evt, x and y as arguments.

pointerdown

Triggered when pointer is pressed down on a target (a mousedown or touchstart event is detected). The paper also starts delegating respective pointermove and pointerup events (including their touch counterparts; see below).

The callback function is passed cellView, evt, x and y as arguments.

cell:pointerdown Triggered when pointer is pressed down on a cell.
link:pointerdown Triggered when pointer is pressed down on a link.
element:pointerdown Triggered when pointer is pressed down on an element.
blank:pointerdown

Triggered when pointer is pressed down on the paper outside any cell.

The callback function is passed evt, x and y as arguments.

pointermove

Triggered when pointer is moved over a target while pressed down (a mousemove or touchmove event is detected).

The callback function is passed cellView, evt, x and y as arguments.

cell:pointermove Triggered when pointer is moved over a cell.
link:pointermove Triggered when pointer is moved over a link.
element:pointermove Triggered when pointer is moved over an element.
blank:pointermove

Triggered when pointer is moved over the paper outside any cell.

The callback function is passed evt, x and y as arguments.

pointerup

Triggered when pointer is released on a target after being pressed down (a mouseup or touchend event is detected).

The callback function is passed cellView, evt, x and y as arguments.

cell:pointerup Triggered when pointer is released on a cell.
link:pointermove Triggered when pointer is relased on a link.
element:pointermove Triggered when pointer is released on an element.
blank:pointermove

Triggered when pointer is released on the paper outside any cell.

The callback function is passed evt, x and y as arguments.

mouseover

Triggered when pointer begins to hover directly over a target.

The callback function is passed cellView and evt as arguments.

cell:mouseover Triggered when pointer begins to hover directly over a cell.
link:mouseover Triggered when pointer begins to hover directly over a link.
element:mouseover Triggered when pointer begins to hover directly over an element.
blank:mouseover

Triggered when pointer begins to hover over the svg element of the paper outside any cell.

The callback function is passed evt as argument.

mouseout

Triggered when pointer ceases to hover directly over a target.

The callback function is passed cellView and evt as arguments.

cell:mouseout Triggered when pointer ceases to hover directly over a cell.
link:mouseout Triggered when pointer ceases to hover directly over a link.
element:mouseout Triggered when pointer ceases to hover directly over an element.
blank:mouseout

Triggered when pointer ceases to hover over the svg element of the paper outside any cell.

The callback function is passed evt as argument.

mouseenter

Triggered when pointer enters the area above a target.

The callback function is passed cellView and evt as arguments.

cell:mouseenter Triggered when pointer enters the area above a cell.
link:mouseenter Triggered when pointer enters the area above a link.
element:mouseenter Triggered when pointer enters the area above an element.
paper:mouseenter

Triggered when pointer enters the area of the paper (including paper border, if present).

The callback function is passed evt as argument.

mouseleave

Triggered when pointer leaves the area above a target.

The callback function is passed cellView and evt as arguments.

cell:mouseleave Triggered when pointer leaves the area above a cell.
link:mouseleave Triggered when pointer leaves the area above a link.
element:mouseleave Triggered when pointer leaves the area above an element.
paper:mouseleave

Triggered when pointer leaves the area of the paper (including paper border, if present).

The callback function is passed evt as argument.

mousewheel

Triggered when mouse wheel is rotated while pointer is on a target.

The callback function is passed cellView, evt, x, y and delta as arguments.

cell:mousewheel Triggered when mouse wheel is rotated while the pointer is on a cell.
link:pointerdblclick Triggered when mouse wheel is rotated while the pointer is on a link.
element:pointerdblclick Triggered when mouse wheel is rotated while the pointer is on an element.
blank:mousewheel

Triggered when mouse wheel is rotated while the pointer is on the paper outside any cell.

The callback function is passed evt, x, y and delta as arguments.

cell:highlight

Triggered when the cellView.highlight method is called on a link or element view.

The callback function is passed cellView and el as arguments.

The default handler method adds the "highlighted" CSS class to the cell, so that it can be targeted in user stylesheets. To use a different method for highlighting cells, first unregister the default handler with paper.off('cell:highlight') and then register a custom handler with paper.on('cell:highlight', myHandler).

This method is also called automatically, in two situations. First, if the user reconnects a link and the connection is valid as determined by the paper.options.validateConnection method. Second, if embedding mode is enabled on the paper and dragged element is above another element it can be dropped onto as determined by the paper.options.validateEmbedding method.

cell:unhighlight

Triggered when the cellView.unhighlight method is called on a link or element view.

The callback function is passed cellView and el as arguments.

The default handler method removes the "highlighted" CSS class from the cell. To use a different method, first unregister the default handler with paper.off('cell:unhighlight') and then register a custom handler with paper.on('cell:unhighlight', myHandler).

It is important to note that if a cell was highlighted using custom options, those exact same options must be provided to the unhighlight handler.

link:connect

Triggered when a link is connected to a cell.

The callback function is passed linkView, evt, elementViewConnected, magnet and arrowhead as arguments.

link:disconnect

Triggered when a link is disconnected from a cell.

The callback function is passed linkView, evt, elementViewDisconnected, magnet and arrowhead as arguments.

rendered:done Triggered when the paper has finished rendering all cell views in case async rendering is enabled.

An example of a simple blank:pointerdown event listener:

paper.on('blank:pointerdown', function(evt, x, y) {
  alert('pointerdown on a blank area in the paper.')
})

Consecutive pointerdown, pointermove and pointerup events can share information through the evt.data object:

// Create a new link by dragging
paper.on({
  'blank:pointerdown': function(evt, x, y) {
    var link = new joint.dia.Link();
    link.set('source', { x: x, y: y });
    link.set('target', { x: x, y: y });
    link.addTo(this.model);
    evt.data = { link: link, x: x, y: y };
  },
  'blank:pointermove': function(evt, x, y) {
    evt.data.link.set('target', { x: x, y: y });
  },
  'blank:pointerup': function(evt) {
    var target = evt.data.link.get('target');
    if (evt.data.x === target.x && evt.data.y === target.y) {
        // remove zero-length links
        evt.data.link.remove();
    }
  }
});
dia.Paper.prototype.cancelRenderViews
paper.cancelRenderViews()

When the method is called any asynchronous rendering in progress is canceled.

dia.Paper.prototype.clearGrid
paper.clearGrid()

Hide the current grid.

dia.Paper.prototype.clientOffset
paper.clientOffset()

Returns coordinates of the paper viewport, relative to the application's client area.

dia.Paper.prototype.clientToLocalPoint
paper.clientToLocalPoint(p)

Transform client coordinates represented by point p to the paper local coordinates. This is especially useful when you have a mouse event object and want coordinates inside the paper that correspond to event clientX and clientY point.

var localPoint1 = paper.clientToLocalPoint({ x: evt.clientX, y: evt.clientY });
// alternative method signature
var localPoint2 = paper.clientToLocalPoint(evt.clientX, evt.clientY);

dia.Paper.prototype.clientToLocalRect
paper.clientToLocalRect(rect)

Transform the rectangle rect defined in the client coordinate system to the local coordinate system.

var bcr = paper.svg.getBoundingClientRect();
var localRect1 = paper.clientToLocalRect({ x: bcr.left, y: bcr.top, width: bcr.width, height: bcr.height });
// alternative method signature
var localRect2 = paper.clientToLocalRect(bcr.left, bcr.top, bcr.width, bcr.height);
// Move the element to the center of the paper viewport.
var localCenter = localRect1.center();
var elSize = element.size();
element.position(localCenter.x - elSize.width, localCenter.y - elSize.height);

dia.Paper.prototype.defineFilter
paper.defineFilter(filterDefinition)

Define an SVG filter for later reuse within the paper. The method returns the filter id and the filterDefinition must have the following form:

{
    name: <name of the filter>,
    args: <filter arguments>
}

Where name is the name of the filter. See below for the list of built-in filters. args is an object containing filter parameters. These parameters are dependent on the filter used and are described in the list below as well. Example usage:

var filterId = paper.defineFilter({
    name: 'dropShadow',
    args: {
        dx: 2,
        dy: 2,
        blur: 3
    }
});

svgNode.setAttribute('filter', 'url(#' + filterId + ');

The following is the list of built-in filters. All these filters are defined in the joint.util.filter namespace. This namespace can be extended simply by adding a new method to it with one argument, an object with filter parameters, returning a string representing the SVG filter definition.

  • blur
    • x - horizontal blur
    • y - vertical blur [optional, if not defined y is the same as x]
  • dropShadow
    • dx - horizontal shift
    • dy - vertical shift
    • blur - blur
    • color - color
    • opacity - opacity
  • grayscale
    • amount - the proportion of the conversion. 1 is completely grayscale. 0 leaves the element unchanged.
  • sepia
    • amount - the proportion of the conversion. 1 is completely sepia. 0 leaves the element unchanged.
  • saturate
    • amount - the proportion of the conversion. 0 is completely un-saturated. 1 leaves the element unchanged.
  • hueRotate
    • angle - the number of degrees around the color circle the input samples will be adjusted
  • invert
    • amount - the proportion of the conversion. 1 is completely inverted. 0 leaves the element unchanged.
  • brightness
    • amount - the proportion of the conversion. 0 makes the element completely black. 1 leaves the element unchanged.
  • contrast
    • amount - the proportion of the conversion. 0 makes the element completely black. 1 leaves the element unchanged.
dia.Paper.prototype.defineGradient
paper.defineGradient(gradientDefinition)

Define an SVG gradient for later reuse within the paper. The method returns the gradient id and the gradientDefinition must have the following form:

{
    type: <type of gradient>,
    stops: <stop colors>,
    attrs: <additional attributes>
}

Where type is either 'linearGradient' or 'radialGradient', attrs is an object containing additional SVG attributes for the SVG gradient element and stops is an array of the ramps of color on the gradient. Each stop object is of the form:

{
    offset: <offset>,
    color: <color>,
    opacity: <opacity>
}

Where offset is a string representing the offset of the gradient stop, color indicates what color to use at that gradient stop and opacity is a number in the [0..1] range representing the transparency of the stop color. Example use:

var gradientId = paper.defineGradient({
    type: 'linearGradient',
    stops: [
        { offset: '0%', color: '#E67E22' },
        { offset: '20%', color: '#D35400' },
        { offset: '40%', color: '#E74C3C' },
        { offset: '60%', color: '#C0392B' },
        { offset: '80%', color: '#F39C12' }
    ]
});

svgNode.setAttribute('fill', 'url(#' + gradientId + ')');

For an introduction to gradients, please refer to the tutorial on Filters and Gradients.

dia.Paper.prototype.defineMarker
paper.defineMarker(markerDefinition)

Define an SVG marker for later reuse within the paper. The method returns the marker id and the markerDefinition is an object with type property and any other visual attributes. The valid values for type are 'path', 'circle', 'ellipse', 'rect', 'polyline' and 'polygon'.

var markerId = paper.defineMarker({
  type: 'path', // SVG Path
  fill: '#666',
  stroke: '#333',
  // The coordinate system for defining the path data
  // ------------------------------------------------
  // 0,0: marker-start, marker-end or marker-mid
  // n,0: n > 0 in path direction
  //      n < 0 opposite path direction
  // 0,m: m > 0 left to the path direction
  //      m < 0 right to the path direction
  d: 'M 10 -10 0 0 10 10 z'
});

// Draw an arrow at the start and the end of a path
svgPath.setAttribute('marker-start', 'url(#' + markerId + ')');
svgPath.setAttribute('marker-end', 'url(#' + markerId + ')');
dia.Paper.prototype.drawBackground
paper.drawBackground(opt);

Sets the paper background defined by the opt object. Please see the background paper option for available configuration.

dia.Paper.prototype.drawGrid
paper.drawGrid([opt])

Draw visual grid lines on the paper. Possible options:

  • color - the color of the grid line (hex, RGB, etc).
  • thickness - the thickness of the grid line (pixels).
dia.Paper.prototype.findView
paper.findView(element)

Find a view (instance of joint.dia.ElementView or joint.dia.LinkView) associated with a DOM element in the paper. element can either be a DOM element, jQuery object or a CSS selector. Sometimes, it is useful to find a view object for an element in the DOM. This method finds the closest view for any subelement of a view element.

dia.Paper.prototype.findViewByModel
paper.findViewByModel(model)

Find a view (instance of joint.dia.ElementView or joint.dia.LinkView) associated with a model. model can either be an instance of joint.dia.Element or joint.dia.Link.

dia.Paper.prototype.findViewsFromPoint
paper.findViewsFromPoint(point)

Find views (instance of joint.dia.ElementView) under a certain point in the paper. point is an object with x and y properties. Returns an array of views whose bounding box contains point. Note that there can be more then one views as views might overlap. Note there is a difference between this method and the joint.dia.Graph:findModelsFromPoint. A bounding box of a view can be different than the area computed by an element model position and size. For example, if a <text> SVG element in the shape is positioned relatively and shifted down below the normal shape area (e.g. using the JointJS special attributes), the bounding box of the view will be bigger than that of the model.

dia.Paper.prototype.findViewsInArea
paper.findViewsInArea(rect [, opt])

Find views (instance of joint.dia.ElementView) in a certain area in the paper. rect is an object with x, y, width and height properties. Return an array of views whose bounding box intersects the rect rectangle.
If opt.strict is true, return an array of views whose bounding box is contained within the rect rectangle (i.e. not only intersects it).

dia.Paper.prototype.fitToContent
paper.fitToContent([opt])

Expand/shrink the paper to fit the content inside it. Snap the resulting width/height to the grid defined by opt.gridWidth / opt.gridHeight. opt.padding adds to the resulting width/height of the paper. The opt.padding can either be a number in which case it represents the padding on all the sides or it can be an object of the form { top: Number, right: Number, bottom: Number, left: Number }. By default the method fits the paper to a content with positive coordinates only and sets the origin to (0,0) for the resulting paper. To change this behaviour use the allowNewOrigin: ['negative'|'positive'|'any'] option. Set allowNewOrigin to 'negative' to account for content with negative coordinates. Set allowNewOrigin to 'positive' to allow origin to be set to the top-left coordinate of the content. Set allowNewOrigin to 'any' to apply both. This method might internally trigger the "resize" and "translate" events that can be handled by listening on the paper object (paper.on('resize', myHandler)). opt.minWidth and opt.minHeight define the minium width and height of the paper and opt.maxWidth and opt.maxHeight define the maximum width and height of the paper after fitting it to the content.
You can try many of these options interactively in the paper demo.

Depracated usage:  paper.fitToContent(gridWidth, gridHeight, padding, opt)

dia.Paper.prototype.getContentArea
paper.getContentArea()

Return a rectangle representing the area occupied by paper content, in local units (without transformations).

dia.Paper.prototype.getContentBBox
paper.getContentBBox()

Return the bounding box of the content inside the paper, in client units (as it appears on the screen).

dia.Paper.prototype.hideTools
paper.hideTools()

Hide all tools attached to all link views on this paper.

dia.Paper.prototype.isDefined
paper.isDefined(graphicalObjectId)

Return true if there is a graphical object (gradient, filter, marker) with graphicalObjectId already defined within the paper. Return false otherwise.

dia.Paper.prototype.localToClientPoint
paper.localToClientPoint(p)

Transform the point p defined in the local coordinate system to the client coordinate system.

var rightMidPoint = element.getBBox().rightMiddle();
var clientPoint1 = paper.localToClientPoint(rightMidPoint);
 // alternative method signature
var clientPoint2 = paper.localToClientPoint(rightMidPoint.x, rightMidPoint.y);
// Draw an HTML rectangle next to the element.
var div = document.createElement('div');
div.style.position = 'fixed';
div.style.background = 'red';
div.style.left = clientPoint1.x + 'px';
div.style.top = clientPoint1.y + 'px';
div.style.width = '40px';
div.style.height = '40px';
div.style.marginLeft = '10px';
div.style.marginTop = '-20px';
document.body.appendChild(div);

dia.Paper.prototype.localToClientRect
paper.localToClientRect(rect)

Transform the rectangle rect defined in local coordinate system to the client coordinate system.

var bbox = element.getBBox();
var clientRect1 = paper.localToClientRect(bbox);
 // alternative method signature
var clientRect2 = paper.localToClientRect(bbox.x, bbox.y, bbox.width, bbox.height);
// Draw an HTML rectangle above the element.
var div = document.createElement('div');
div.style.position = 'fixed';
div.style.background = 'red';
div.style.left = clientRect1.x + 'px';
div.style.top = clientRect1.y + 'px';
div.style.width = clientRect1.width + 'px';
div.style.height = clientRect1.height + 'px';
paper.el.appendChild(div);

dia.Paper.prototype.localToPagePoint
paper.localToPagePoint(p)

Transform the point p defined in the local coordinate system to the page coordinate system.

var rightMidPoint = element.getBBox().rightMiddle();
var pagePoint1 = paper.localToPagePoint(rightMidPoint);
 // alternative method signature
var pagePoint2 = paper.localToPagePoint(rightMidPoint.x, rightMidPoint.y);
// Draw an HTML rectangle next to the element.
var div = document.createElement('div');
div.style.position = 'absolute';
div.style.background = 'red';
div.style.left = pagePoint1.x + 'px';
div.style.top = pagePoint1.y + 'px';
div.style.width = '40px';
div.style.height = '40px';
div.style.marginLeft = '10px';
div.style.marginTop = '-20px';
document.body.appendChild(div);

dia.Paper.prototype.localToPageRect
paper.localToPageRect(rect)

Transform the rectangle rect defined in local coordinate system to the page coordinate system.

var bbox = element.getBBox();
var pageRect1 = paper.localToPageRect(bbox);
 // alternative method signature
var pageRect2 = paper.localToPageRect(bbox.x, bbox.y, bbox.width, bbox.height);
// Draw an HTML rectangle above the element.
var div = document.createElement('div');
div.style.position = 'absolute';
div.style.background = 'red';
div.style.left = pageRect1.x + 'px';
div.style.top = pageRect1.y + 'px';
div.style.width = pageRect1.width + 'px';
div.style.height = pageRect1.height + 'px';
document.body.appendChild(div);

dia.Paper.prototype.localToPaperPoint
paper.localToPaperPoint(p)

Transform the point p defined in the local coordinate system to the paper coordinate system.

var rightMidPoint = element.getBBox().rightMiddle();
var paperPoint1 = paper.localToPaperPoint(rightMidPoint);
 // alternative method signature
var paperPoint2 = paper.localToPaperPoint(rightMidPoint.x, rightMidPoint.y);
// Draw an HTML rectangle next to the element.
var div = document.createElement('div');
div.style.position = 'absolute';
div.style.background = 'red';
div.style.left = paperPoint1.x + 'px';
div.style.top = paperPoint1.y + 'px';
div.style.width = '40px';
div.style.height = '40px';
div.style.marginLeft = '10px';
div.style.marginTop = '-20px';
paper.el.appendChild(div); 

dia.Paper.prototype.localToPaperRect
paper.localToPaperRect(rect)

Transform the rectangle rect defined in the local coordinate system to the paper coordinate system.

var bbox = element.getBBox();
var paperRect1 = paper.localToPaperRect(bbox);
 // alternative method signature
var paperRect2 = paper.localToPaperRect(bbox.x, bbox.y, bbox.width, bbox.height);
// Draw an HTML rectangle above the element.
var div = document.createElement('div');
div.style.position = 'absolute';
div.style.background = 'red';
div.style.left = paperRect1.x + 'px';
div.style.top = paperRect1.y + 'px';
div.style.width = paperRect1.width + 'px';
div.style.height = paperRect1.height + 'px';
paper.el.appendChild(div);

dia.Paper.prototype.matrix
paper.matrix([SVGMatrix])

When called with no parameter, the method returns the current transformation matrix (instance of SVGMatrix) of the paper. It sets the new viewport transformation based on the SVGMatrix otherwise.

paper.matrix({ a: 2, b: 0, c: 0, d: 2, e: 0, f: 0 }); // scale the paper twice
dia.Paper.prototype.pageOffset
paper.pageOffset()

Returns coordinates of the paper viewport, relative to the document.

dia.Paper.prototype.pageToLocalPoint
paper.pageToLocalPoint(p)

Transform the point p defined in the page coordinate system to the local coordinate system.

paper.on('blank:pointerup', function(evt) {
  var pagePoint = g.Point(evt.pageX, evt.pageY);
  var localPoint1 = this.pageToLocalPoint(pagePoint);
  // alternative method signature
  var localPoint2 = this.pageToLocalPoint(evt.pageX, evt.pageY);
  // Move the element to the point, where the user just clicks.
  element.position(localPoint1.x, localPoint1.y);
});

dia.Paper.prototype.pageToLocalRect
paper.pageToLocalRect(rect)

Transform the rectangle rect defined in the page coordinate system to the local coordinate system.

var x, y;
paper.on('blank:pointerdown', function(evt) {
  x = evt.pageX;
  y = evt.pageY;
});
paper.on('blank:pointerup', function(evt) {
  var pageRect = g.Rect(x, y, evt.pageX - x, evt.pageY - y).normalize();
  var localRect1 = this.pageToLocalRect(pageRect);
  // alternative method signature
  var localRect2 = this.pageToLocalRect(x, y, evt.pageX - x, evt.pageY - y).normalize();
  // Move and resize the element to cover the area, that the user just selected.
  element.position(localRect1.x, localRect1.y);
  element.resize(localRect1.width, localRect1.height);
});

dia.Paper.prototype.paperToLocalPoint
paper.paperToLocalPoint(p)

Transform the point p defined in the paper coordinate system to the local coordinate system.

var paperCenter = g.Point(paper.options.width / 2, paper.options.height / 2);
var localPoint1 = paper.paperToLocalPoint(paperCenter);
 // alternative method signature
var localPoint2 = paper.paperToLocalPoint(paper.options.width / 2, paper.options.height / 2);
// Move the element to the center of the paper viewport.
var elSize = element.size();
element.position(localPoint1.x - elSize.width, localPoint1.y - elSize.height);

dia.Paper.prototype.paperToLocalRect
paper.paperToLocalRect(rect)

Transform the rectangle rect defined in the paper coordinate system to the local coordinate system.

var paperRect = g.Rect(0, 0, paper.options.width, paper.options.height);
var localRect1 = paper.paperToLocalRect(paperRect);
 // alternative method signature
var localRect2 = paper.paperToLocalRect(0, 0, paper.options.width, paper.options.height);
// Move and resize the element to cover the entire paper viewport.
element.position(localRect1.x , localRect1.y);
element.size(localRect1.width, localRect1.height);

dia.Paper.prototype.properties

The following list contains properties exposed by the paper object:

  • svg - a reference to the SVG document object the paper uses to render all the graphics.
  • viewport - a reference to the SVG group <g> element the paper wraps all the rendered elements and links into. Paper transformations such as scale is performed on this element.
  • defs - a reference to the SVG <defs> element used to define SVG elements for later reuse. This is also a good place to put SVG masks, patterns, filters and gradients.

Normally, you do not need to access these properties directly but in some (advanced) situations, it is handy to have access to them.

dia.Paper.prototype.removeTools
paper.removeTools()

Remove all tools view objects attached to all link views on this paper.

dia.Paper.prototype.scale
paper.scale([sx, sy, ox, oy])

Scale a paper by sx factor in x axis and sy factor in y axis. ox and oy are optional and determine the origin of the scale transformation. This method effectively implements a paper zoom in/out. If the method is called a "scale" event is triggered on the paper. When the method is called with no parameter the current paper scale transformation is returned.

paper.scale(2) // scale 2x (uniformly)
paper.scale(2,3) // scale 2x in `x` axis 3x in `y` axis (non-uniformly)
paper.scale(2,2,100,100) // scale with the origin of the transformation at point `x=100` and `y=100`
paper.scale() // returns e.g. { sx: 2, sy: 2 }
dia.Paper.prototype.scaleContentToFit
paper.scaleContentToFit([opt])

Scale the paper content so that it fits the paper dimensions. If opt.padding is set (default is 0), there will be an additional padding in the resulting, scaled, paper content. If opt.preserveAspectRatio is defined (default is true), the aspect ratio of the scaled paper content will be preserved. opt.minScaleX, opt.minScaleY, opt.maxScaleX and opt.maxScaleY can be optionally used to set the minimum and maximum allowed scale factor for both axis. opt.scaleGrid is a number that will be used to as a rounding factor for the resulting scale. For example, if the resulting scale factor is calculated to be 1.15 and your opt.scaleGrid is set to 0.2, then the resulting scale factor will be rounded to 1.2. Last option is opt.fittingBBox which can be an object of the form { x: [number], y: [number], width: [number], height: [number] } and is the area of the paper that should be scaled. By default opt.fittingBBox is { x: 0, y: y, width: paper.options.width, height: paper.options.height }, i.e. the whole paper area. If the method called a "scale" event can be triggered on the paper. To try it yourself see paper demo.

dia.Paper.prototype.setDimensions
paper.setDimensions(width, height)

Change dimensions of a paper. Dimensions should always be passed to the options object of the joint.dia.Paper constructor. Use setDimensions() to change dimensions of the paper later on if needed. If the method is called a "resize" event is triggered on the paper.

dia.Paper.prototype.setGridSize
paper.setGridSize(gridSize)

Set the grid size of the paper.

dia.Paper.prototype.setInteractivity
paper.setInteractivity(interactive)

Set the interactivity of the paper. For example, to disable interactivity:

paper.setInteractivity(false);
dia.Paper.prototype.setOrigin
paper.setOrigin(x, y)

Deprecated in favor of translate(). Lets you modify the origin (zero coordinates) of a paper. An origin can also be passed to the options object of the joint.dia.Paper constructor. If the method is called a "translate" event is triggered on the paper.

dia.Paper.prototype.showTools
paper.showTools()

Show all tools attached to all link views on this paper.

dia.Paper.prototype.translate
paper.translate(x, y)

Lets you modify the origin (zero coordinates) of a paper. An origin can also be passed to the options object of the joint.dia.Paper constructor. If the method is called a "translate" event is triggered on the paper. If the method is called with no paramater the current paper translate transformation is returned.

paper.translate(100, 200) // set origin to `x=100` and `y=200`
paper.translate(100) // same as calling `translate(100,0)`
paper.translate() // returns e.g. { tx: 100, ty: 100 }
dia.Paper.prototype.options.async
async - when enabled, the paper renders cells added to the graph through graph.resetCells() or graph.addCells() asynchronously. This is very useful when you want to add a large number of cells into the graph. The rendering performance boost is significant and doesn't block the UI. The option accepts either true in which case default values are used or an object of the form { batchSize: <value> } where you can specify the number of cells rendered in each animation frame (default is 50). Normally, the default batchSize works great but you might want to experiment with different values in case you encounter performance issues. It is important to note that when asynchronous rendering is used, some of the cell views might not yet be in the paper when you try to access them via the paper.findViewByModel(), element.findView() or link.findView() methods. What you should do in case you use async rendering is to wait for when the paper triggers the render:done event.
dia.Paper.prototype.options.background

An object defining the paper background color and image. It defaults to false meaning there is no background set. The configuration object can have the following properties.

  • color property sets the paper background color. It accepts all the values accepted by the CSS background-color property. e.g 'red', 'rgba(255, 255, 0, 0.5)', 'radial-gradient(ellipse at center, red, green);'
  • image property defines the path to the background image file. e.g. '/my-background.png'.
  • position is an object { x: Number, y: Number } defining the background image position. It also allows to use all the CSS background-position property values. In that case all the paper transformations have no impact on the background image position. It defaults to center.
  • size is an object { width: Number, height: Number } defining the background image size. It also allows to use all the CSS background-size property values. In that case all the paper transformations have no impact on the background size. It defaults to auto auto.
  • repeat property defines how the background image is repeated. The value could be any value accepted by the CSS background-repeat property and few more defined by JointJS. Those are flip-x, flip-y, flip-xy and watermark. It defaults to no-repeat.
  • quality is a coefficient specifying the quality of the image (e.g 0.5 uses only 50% the image size for creating a pattern). Applicable only for the JointJS repeat option values. It defaults to 1.
  • opacity is a number in the range [0,1] specifying the transparency of the background image (0 is fully transparent and 1 is fully opaque). It defaults to 1.
  • watermarkAngle is an angle in degrees speficying the slope of the watermark image. Applicable only for the 'watermark' repeat option. It defaults to 20 deg.
background: {
   color: '#6764A7',
   image: 'jointjs-logo.png',
   repeat: 'watermark',
   opacity: 0.3
}
dia.Paper.prototype.options.cellViewNamespace
cellViewNamespace - this option can be used to change the default behavior of JointJS which by default reads cell view definitions from the joint.shapes namespace. For example, if a cell is of type 'myshapes.MyElement', then the paper looks up joint.shapes.myshapes.MyElementView object type when rendering the cell onto the screen. If cellViewNamespace is set, the paper will read the view definition from the myShapesNamespace.myshapes.MyElementView object instead. This is useful in situations where you - for any reason - don't want to use the joint.shapes namespace for defining your own custom shapes. This option is often used in combination with cellNamespace option on the joint.dia.Graph object.
dia.Paper.prototype.options.clickThreshold
clickThreshold - When number of mousemove events exceeds the clickThreshold there is no pointerclick event triggered after mouseup. It defaults to 0.
dia.Paper.prototype.options.connectionStrategy
connectionStrategy - the connection strategy to use on this paper. It can either be a function or null. JointJS provides a collection of built-in connection strategies in the joint.connectionStrategies namespace; alternatively, a custom function may be provided. See the Presentation section of joint.dia.Link for more information about connection strategies.
dia.Paper.prototype.options.defaultAnchor
defaultAnchor - an anchor function that is used by links if no anchor property is defined for a link end. It can either be an object (with a name and optional args) or a function. JointJS provides a collection of built-in anchor functions in the joint.anchors namespace; alternatively, a custom function may be provided. See the Presentation section of joint.dia.Link for more information about anchors.
dia.Paper.prototype.options.defaultConnectionPoint
defaultConnectionPoint - a connection point function that is used by links if no connectionPoint property is defined for a link end. It can either be an object or a function. JointJS provides a collection of built-in connection point functions in the joint.connectionPoints namespace; alternatively, a custom function may be provided. See the Presentation section of joint.dia.Link for more information about connection points.
dia.Paper.prototype.options.defaultConnector
defaultConnector - a connector that is used by links if no connector property is defined on them. It can either be an object or a function. JointJS provides a collection of built-in connectors in the joint.connectors namespace; alternatively, a custom function may be provided. See the Presentation section of joint.dia.Link for more information about connectors.
dia.Paper.prototype.options.defaultRouter
defaultRouter - a router that is used by links if no router property is defined on them. It can either be an object or a function. JointJS provides a collection of built-in routers in the joint.routers namespace; alternatively, a custom function may be provided. See the Presentation section of joint.dia.Link for more information about routers.
dia.Paper.prototype.options.drawGrid

drawGrid - option whether the paper grid should be drawn or not. It could be a boolean or an object. It defaults to false.
Define color and thickness to adjust the default grid pattern:

color string color of the default grid pattern.
thickness number thickness of the default grid pattern.

There are also some pre-defined grid patterns: dot, fixedDot, mesh, doubleMesh. If you'd like to use these patterns, define drawGrid options as follows:

name string name of the pre-defined pattern. Can be either dot, fixedDot, mesh, doubleMesh
args object | array an extra arguments for the pre-defined grid patterns. It can be either an object (e.g. dot, mesh) or an array (e.g. doubleMesh)

Pre-defined grids with default settings:

The paper from the images below has been scaled 2 times and has gridSize set to 10.

dot
fixedDot
mesh
doubleMesh
drawGrid: true // default pattern (dot) with default settings

drawGrid: 'mesh' // pre-defined pattern with default settings
drawGrid: { name: 'mesh', args: { color: 'black' }}

drawGrid: {
    name: 'doubleMesh',
    args: [
        { color: 'red', thickness: 1 }, // settings for the primary mesh
        { color: 'green', scaleFactor: 5, thickness: 5 } //settings for the secondary mesh
]}
dia.Paper.prototype.options.el
el - CSS selector, jQuery object or a DOM element holding the container for the paper
dia.Paper.prototype.options.elementView
elementView - object that is responsible for rendering an element model into the paper. Defaults to joint.dia.ElementView. It can also be a function of the form function(element) that takes an element model and should return an object responsible for rendering that model onto the screen (in most cases a subtype of joint.dia.ElementView)
dia.Paper.prototype.options.embeddingMode
embeddingMode - when set to true, the paper is set to embedding mode. In this mode, when you drag an element and drop into another element, the element below becomes a parent of the dropped element (the dropped element gets automatically embedded into the parent element). Similarly, when you drag an element out of its parent, the element gets automatically unembedded from its parent. The embedding mode also makes sure all the connected links and child elements have proper z index set so that they stay visible. To control what elements can be embedded into what other elements, use the validateEmbedding() function on the paper (see below). This is useful for hierarchical diagrams. See the DEVS demo on how this can be used.
dia.Paper.prototype.options.findParentBy
findParentBy - determines the way how a cell finds a suitable parent when it's dragged over the paper. The cell with the highest z-index (visually on the top) will be chosen. findParentBy option comes to play when the paper is in embedding mode. All possible values are 'bbox' (default), 'center', 'origin', 'corner', 'topRight', 'bottomLeft' and it also can be a function. The function accepts an element and it returns array of possible candidates.
findParentBy: function(element) {
    var bBox = element.getBBox();
    return this.getElements().filter(function(el) {
        return bBox.intersect(el.getBBox());
    });
}
dia.Paper.prototype.options.gridSize
gridSize - size of the grid in pixels
dia.Paper.prototype.options.guard
guard - guard paper from handling a browser UI event. This function is of the form function(evt, view) and should return true if you want to prevent the paper from handling the event evt, false otherwise. This is an advanced option that can be useful if you have your own logic for handling events.
dia.Paper.prototype.options.height
height - height of the paper in pixels
dia.Paper.prototype.options.highlighting

highlighting - Configure which highlighter to use (and with which options) for each type of interaction.

List of highlighting interactions
  • default - the default highlighter to use (and options) when none is specified
  • connecting - when a valid link connection can be made to an element
  • embedding - when a cell is dragged over another cell in embedding mode
  • magnetAvailability - when showing all magnets to which a valid connection can be made
  • elementAvailability - when showing all elements to which a valid connection can be made

Example usage:

new joint.dia.Paper({
    highlighting: {
        'default': {
            name: 'stroke',
            options: {
                padding: 3
            }
        },
        connecting: {
            name: 'addClass',
            options: {
                className: 'highlight-connecting'
            }
        }
    }
})
dia.Paper.prototype.options.interactive

interactive - Configure which of the default interactions with elements and links should be enabled.

The property value defaults to { labelMove: false }. This can be overwritten in three ways: with a boolean value, with an object specifying interaction keys, or with a function.

If set to false, all interactions with elements and links are disabled. If set to true, all interactions are enabled.

// disable all interaction
var paper = new joint.dia.Paper({
    // ...
    interactive: false,
});

// enable all interaction (including labelMove)
var paper = new joint.dia.Paper({
    // ...
    interactive: true,
});

Using an object, specific interactions may be disabled by assigning false to their corresponding property name. It is not necessary to pass true values; all omitted properties are assigned true by default. (Note that the passed object is not merged with the default; unless labelMove is explicitly excluded, it becomes enabled.) A full list of recognized interaction keys is provided below.

// disable arrowheadMove
var paper = new joint.dia.Paper({
    // ...
    interactive: { arrowheadMove: false }
});

// disable all element interactions
var paper = new joint.dia.Paper({
    // ...
    interactive: { elementMove: false, addLinkFromMagnet: false }
});

If defined as a function, the function is passed cellView (the elementView/linkView the user is about to interact with) as the first parameter, followed by the name of the event ('pointerdown', 'pointermove', ...) that triggered the interaction. The return value of the function is then interpreted in the way specified above (false causes all interaction to be disabled, an object disables specific interactions, etc.).

// disable link interactions for cellViews when a custom property is set
var paper = new joint.dia.Paper({
    // ...
    interactive: function(cellView) {
        if (cellView.model.get('disableLinkInteractions')) {
            return {
                arrowheadMove: false,
                vertexMove: false,
                vertexAdd: false,
                vertexRemove: false,
                labelMove: false,
                useLinkTools: false
            };
        }

        // otherwise
        return true;
    }
});

The following tables present a list of all recognized interaction keys, followed by an example paper with the related interactive property set to false.

Links:

arrowheadMove vertexMove
vertexAdd vertexRemove
labelMove useLinkTools

Elements:

elementMove addLinkFromMagnet

For comparison, the example below has all interactions on the link and on the elements enabled.

dia.Paper.prototype.options.linkConnectionPoint
linkConnectionPoint(linkView, view, magnet, reference) - this function allows you to customize what are the sticky points of links. The function must return a point (with x and y properties) where the link sticks to the element. The function takes the link view, element view, the magnet (SVG element) the link should stick to and a reference point (either the closest vertex or the sticky point on the other side of the link). Note that there is a utility function shapePerimeterConnectionPoint that can be directly passed to the linkConnectionPoint parameter. This function tries to find the best possible connection point right on the perimeter of the connected shapes. See the function documentation for details.
dia.Paper.prototype.options.linkPinning
linkPinning - when set to true (the default), links can be pinned to the paper meaning a source or target of a link can be a point. If you do not want to let the user drag a link and drop it somewhere in a blank paper area, set this to false. The effect is that the link will be returned to its original position whenever the user drops it somewhere in a blank paper area.
dia.Paper.prototype.options.linkView
linkView - object that is responsible for rendering a link model into the paper. Defaults to joint.dia.LinkView. It can also be a function of the form function(link) that takes a link model and should return an object responsible for rendering that model onto the screen (in most cases a subtype of joint.dia.LinkView).
dia.Paper.prototype.options.markAvailable
markAvailable - marks all the available magnets or elements when a link is dragged (being reconnected). Default is false. This gives a hint to the user to what other elements/ports this link can be connected. What magnets/cells are available is determined by the validateConnection function. Internally, available magnets (SVG elements) are given the 'available-magnet' class name and all the available cells the 'available-cell' class name. This allows you to change the styling of the highlight effect.
dia.Paper.prototype.options.model
model - joint.dia.Graph object
dia.Paper.prototype.options.moveThreshold
moveThreshold - Number of required mousemove events before the first pointermove event is triggered. It defaults to 0.
dia.Paper.prototype.options.origin
origin - position of zero coordinates of the paper in pixels (default is { x: 0, y: 0 } i.e. top-left corner)
dia.Paper.prototype.options.preventContextMenu
preventContextMenu - Prevents default context menu action (when right button of the mouse is clicked). It defaults to true.
dia.Paper.prototype.options.preventDefaultBlankAction
preventDefaultBlankAction - Prevents default action when an empty paper area is clicked. Setting the option to false will make the paper pannable inside a container on touch devices. It defaults to true.
dia.Paper.prototype.options.restrictTranslate
restrictTranslate - restrict the translation (movement) of elements by a given bounding box. If set to true, the user will not be able to move elements outside the boundary of the paper area. It's set to false by default. This option also accepts a function with signature function(elementView) in which case it must return a bounding box (an object of the form { x: Number, y: Number, width: Number, height: Number }) that defines the area in which the element represented by elementView can be moved. For example, to restrict translation of embedded elements by the bounding box defined by their parent element, you can do:

restrictTranslate: function(elementView) {
    var parentId = elementView.model.get('parent');
    return parentId && this.model.getCell(parentId).getBBox();
}
dia.Paper.prototype.options.validateConnection
validateConnection(cellViewS, magnetS, cellViewT, magnetT, end, linkView) - decide whether to allow or disallow a connection between the source view/magnet (cellViewS/magnetS) and target view/magnet (cellViewT/magnetT). end is either "source" or "target" and tells which end of the link is being dragged. This is useful for defining whether, for example, a link starting in a port POut of element A can lead to a port PIn of elmement B. By default, all linkings are allowed.
dia.Paper.prototype.options.validateEmbedding
validateEmbedding - a function that allows you to control what elements can be embedded to what other elements when the paper is put into the embeddingMode (see above). The function signature is: function(childView, parentView) and should return true if the childView element can be embedded into the parentView element. By default, all elements can be embedded into all other elements (the function returns true no matter what).
dia.Paper.prototype.options.validateMagnet
validateMagnet(cellView, magnet) - decide whether to create a link if the user clicks a magnet. magnet is the DOM element representing the magnet. By default, this function returns true for magnets that are not explicitely set to "passive" (which is usually the case of input ports).
dia.Paper.prototype.options.width
width - width of the paper in pixels

dia.ToolsView

The joint.dia.ToolsView class works as a container for one set of link tools (an array of joint.dia.ToolView objects). It is responsible for rendering the tools as a group when the tools view is attached to a joint.dia.LinkView.

To create a new tools view object, we call its constructor. Two optional arguments are accepted:

name string The name of this tools view. Default is null (no name).
tools Array<dia.ToolView> An array of tools that should be a part of the tools view. Default is [] (no tools).

Creating a tools view is the second step in the process of setting up link tools on a link view:

// 1) creating link tools
var verticesTool = new joint.linkTools.Vertices();
var segmentsTool = new joint.linkTools.Segments();
var boundaryTool = new joint.linkTools.Boundary();

// 2) creating a tools view
var toolsView = new joint.dia.ToolsView({
    name: 'basic-tools',
    tools: [verticesTool, segmentsTool, boundaryTool]
});

// 3) attaching to a link view
var linkView = link.findView(paper);
linkView.addTools(toolsView);

Every link view we want to attach to requires its own tools view object (ToolsView objects are automatically reassigned to the last link view they are added to). Similarly, every tools view we create requires its own set of tools (ToolView objects are automatically reassigned to the last toolsView.tools array they were made part of).

dia.ToolsView.prototype.blurTool
toolsView.blurTool(tool)

Stop focusing the specified tool (of the joint.dia.ToolView type) within this tools view.

This function reverses the effect of the toolsView.focusTool function.

dia.ToolsView.prototype.focusTool
toolsView.focusTool(tool)

Focus the specified tool (of the joint.dia.ToolView type) within this tools view.

When a tool is focused, all other tools within this tools view are hidden and the tool's opacity is changed according to the tool's focusOpacity option. Only one tool can be focused at a time; the focus passes to the last tool within this tools view with which the focusTool function was called.

The effect of this function can be reversed by the toolsView.blurTool function.

dia.ToolsView.prototype.getName
toolsView.getName()

Return the name of this tools view. If no name was set during the construction of the tools view, null is returned.

dia.ToolsView.prototype.hide
toolsView.hide()

Hide all tools within this tools view.

dia.ToolsView.prototype.show
toolsView.show()

Show all tools within this tools view.

dia.ToolView

The joint.dia.ToolView class is the parent class of all link tool views included in the joint.linkTools namespace. It is responsible for rendering the tool within a joint.dia.ToolsView, when the tools view is attached to a joint.dia.LinkView.

Creating link tools objects is the first step in the process of setting up link tools on a link view:

// 1) creating link tools
var verticesTool = new joint.linkTools.Vertices();
var segmentsTool = new joint.linkTools.Segments();
var boundaryTool = new joint.linkTools.Boundary();

// 2) creating a tools view
var toolsView = new joint.dia.ToolsView({
    name: 'basic-tools',
    tools: [verticesTool, segmentsTool, boundaryTool]
});

// 3) attaching to a link view
var linkView = link.findView(paper);
linkView.addTools(toolsView);

Every link view we want to attach to requires its own tools view object (ToolsView objects are automatically reassigned to the last link view they are added to). Similarly, every tools view we create requires its own set of tools (ToolView objects are automatically reassigned to the last toolsView.tools array they were made part of).

dia.ToolView.prototype.blur
toolView.blur()

Stop focusing the tool within its containing toolsView.

This function reverses the effect of the toolView.focus function.

dia.ToolView.prototype.focus
toolView.focus()

Focus the tool within its containing toolsView.

When a tool is focused, all other tools within the toolsView are hidden and the tool's opacity is changed according to the tool's focusOpacity option. Only one tool can be focused at a time; the focus passes to the last tool within a tools view on which the focus function was called.

The effect of this function can be reversed by the toolView.blur function.

dia.ToolView.prototype.getName
toolView.getName()

Return the name of the tool. The names of built-in link tools are kebab-case versions of their class names (e.g. the name of joint.linkTools.SourceAnchor is 'source-anchor').

When creating a custom tool (e.g. by extending the joint.linkTools.Button class), it is recommended that you provide a custom name prototype property, as well:

joint.linkTools.InfoButton = joint.linkTools.Button.extend({
    name: 'info-button',
    options: {
        markup: [{
            tagName: 'circle',
            selector: 'button',
            attributes: {
                'r': 7,
                'fill': '#001DFF',
                'cursor': 'pointer'
            }
        }, {
            tagName: 'path',
            selector: 'icon',
            attributes: {
                'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
                'fill': 'none',
                'stroke': '#FFFFFF',
                'stroke-width': 2,
                'pointer-events': 'none'
            }
        }],
        distance: 60,
        offset: 0,
        action: function(evt) {
            alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
        }
    }
});
dia.ToolView.prototype.hide
toolView.hide()

Hide the tool.

The effect of this function can be reversed by the toolView.show function.

dia.ToolView.prototype.isVisible
toolView.isVisible()

Return true if the tool is currently visible.

A tool is not visible if it has been hidden (e.g. with the toolView.hide function) or if another tool within the containing toolsView has been focused (e.g. with the toolView.focus function).

dia.ToolView.prototype.show
toolView.show()

Show the tool.

The effect of this function can be reversed by the toolView.hide function.

env.addTest

env.addTest(name, fn)

Add a custom feature-detection test where name is a string which uniquely identifies your feature test and fn is a function that returns true if the browser supports the feature, and false if it does not.

joint.env.addTest('customTest', function() {
	// Just as an example, we will always return true here.
	return true;
});

if (joint.env.test('customTest')) {
    // Feature is supported.
}

env.test

env.test(name)

Tests whether the browsers supports the given feature or not. Returns true if the feature is supported, otherwise it returns false.

if (joint.env.test('someFeature')) {
    // Feature is supported.
}

JointJS ships with the following tests:

  • svgforeignobject - Tests whether the browser supports foreignObject.

highlighters

Highlighters can be used to provide visual emphasis to an element; during user interactions for example.

In the above demo, we listen to the paper for the cell:pointerclick event, then highlight the cell that was clicked.

paper.on('cell:pointerclick', function(cellView) {
    cellView.highlight();
});

As you can see it is possible to highlight a cell as follows:

cellView.highlight();

Unhighlighting a cell is simple too:

cellView.unhighlight();

To highlight a cell using a specific highlighter (and options):

cellView.highlight(null/* defaults to cellView.el */, {
    highlighter: {
        name: 'stroke',
        options: {
            width: 3
        }
    }
});

Or you can specify just the highlighter's name (its default options will be used):

cellView.highlight(null/* defaults to cellView.el */, {
    highlighter: 'stroke'
});

highlighters.addClass

Toggles a class name on the cell view's $el.

Available options:

  • className - the class name to toggle on the cell's $el

Example usage:

cellView.highlight(null/* defaults to cellView.el */, {
    highlighter: {
        name: 'addClass',
        options: {
            className: 'some-custom-class'
        }
    }
});

highlighters.opacity

Changes the opacity of the cell view's $el.

When a cell is highlighted with the opacity highlighter, its $el is given the .joint-highlight-opacity class. To customize the look of this highlighted state, you can add custom CSS rules that affect this class name.

This highlighter does not currently have any options.

Example usage:

cellView.highlight(null/* defaults to cellView.el */, {
    highlighter: {
        name: 'opacity'
    }
});

highlighters.stroke

Adds a stroke around the cell view's $el.

Available options:

  • padding - the space between the stroke and the element
  • rx - the stroke's border radius on the x-axis
  • ry - the stroke's border radius on the y-axis
  • attrs - an object with SVG attributes to be set on the highlighter element

Example usage:

cellView.highlight(null/* defaults to cellView.el */, {
    highlighter: {
        name: 'stroke',
        options: {
            padding: 10,
            rx: 5,
            ry: 5,
            attrs: {
                'stroke-width': 3,
                stroke: '#FF0000'
            }
        }
    }
});

layout.DirectedGraph

Automatic layout of directed graphs. This plugin uses the open-source (MIT license) Dagre library internally. It provides a wrapper so that you can call the layout directly on JointJS graphs.

Note that you must include both the Dagre and Graphlib libraries as dependencies if you wish to use the layout.DirectedGraph plugin.

Usage

joint.layout.DirectedGraph plugin exposes the joint.layout.DirectedGraph.layout(graphOrElements, opt) function. The first parameter graphOrElements is the joint.dia.Graph or an array of joint.dia.Elements we want to layout. The second parameter options is an object that contains various options for configuring the layout.

var graphBBox = joint.layout.DirectedGraph.layout(graph, {
    nodeSep: 50,
    edgeSep: 80,
    rankDir: "TB"
});
console.log('x:', graphBBox.x, 'y:', graphBBox.y)
console.log('width:', graphBBox.width, 'height:', graphBBox.height);

A full blog post explaining this example in more detail can be found here.

Example with clusters

Configuration

The following table lists options that you can pass to the joint.layout.DirectedGraph.layout(graph, opt) function:

nodeSepa number of pixels representing the separation between adjacent nodes in the same rank
edgeSepa number of pixels representing the separation between adjacent edges in the same rank
rankSepa number of pixels representing the separation between ranks
rankDirdirection of the layout (one of "TB" (top-to-bottom) / "BT" (bottom-to-top) / "LR" (left-to-right) / "RL" (right-to-left))
marginXnumber of pixels to use as a margin around the left and right of the graph.
marginYnumber of pixels to use as a margin around the top and bottom of the graph.
rankerType of algorithm to assign a rank to each node in the input graph. Possible values: 'network-simplex' (default), 'tight-tree' or 'longest-path'. number of pixels to use as a margin around the top and bottom of the graph.
resizeClustersset to false if you don't want parent elements to stretch in order to fit all their embedded children. Default is true.
clusterPaddingA gap between the parent element and the boundary of its embedded children. It could be a number or an object e.g. { left: 10, right: 10, top: 30, bottom: 10 }. It defaults to 10.
setPosition(element, position)a function that will be used to set the position of elements at the end of the layout. This is useful if you don't want to use the default element.set('position', position) but want to set the position in an animated fashion via transitions.
setVertices(link, vertices) If set to true the layout will adjust the links by setting their vertices. It defaults to false. If the option is defined as a function it will be used to set the vertices of links at the end of the layout. This is useful if you don't want to use the default link.set('vertices', vertices) but want to set the vertices in an animated fashion via transitions.
setLabels(link, labelPosition, points) If set to true the layout will adjust the labels by setting their position. It defaults to false. If the option is defined as a function it will be used to set the labels of links at the end of the layout. Note: Only the first label (link.label(0);) is positioned by the layout.

Additionally, the layout engine takes into account some properties on elements/links to fine tune the layout further. These are:

size element An object with `width` and `height` properties representing the size of the element.
minLen link The number of ranks to keep between the source and target of the link.
weight link The weight to assign edges. Higher weight edges are generally made shorter and straighter than lower weight edges.
labelPosition link Where to place the label relative to the edge. 'l' = left, 'c' = center (default), 'r' = right.
labelOffset link How many pixels to move the label away from the edge. Applies only when labelPosition is left or right.
labelSize link The width and height of the edge label in pixels. e.g. { width: 100, height: 50 }

The layout() function returns a bounding box (g.Rect) of the resulting graph.

API

The layout.DirectedGraph plugins extends the joint.dia.Graph type with functions that make it easy to convert graphs to and from the Graphlib graph format. This allows you to easily use many of the graph algorithms provided by this library.

toGraphLib()

Convert the JointJS joint.dia.Graph object to the Graphlib graph object.

var graph = new joint.dia.Graph;
// ... populated the graph with elements connected with links
graphlib.alg.isAcyclic(graph.toGraphLib())      // true if the graph is acyclic

fromGraphLib(glGraph, opt)

Convert the Graphlib graph representation to JointJS joint.dia.Graph object. opt.importNode and opt.importEdge are functions that accept a Graphlib node and edge objects and should return JointJS element/link.

var g = new graphlib.Graph();
g.setNode(1);
g.setNode(2);
g.setNode(3);
g.setEdge(1, 2);
g.setEdge(2, 3);

var graph = new joint.dia.Graph;
graph.fromGraphLib(g, {
    importNode: function(node) {
        return new joint.shapes.basic.Rect({
            position: { x: node.x, y: node.y },
            size: { width: node.width, height: node.height }
        });
    },
    importEdge: function(edge) {
        return new joint.dia.Link({
            source: { id: edge.v },
            target: { id: edge.w }
        });
    }
});

layout.Port

Port layouts are functions that accept an array of port's args and return an array of port positions. Positions are relative to the element model bounding box. For example if we have an element at position { x:10, y:20 } with a relative port position { x:1, y:2 }, the absolute port position will be { x:11, y:22 }.

Port layout can be defined only at the group level. Optionally you can pass some additional arguments into the layout function via args. The args is the only way to adjust port layout from the port definition perspective.

var rect = new joint.shapes.basic.Rect({
    // ...
    ports: {
        groups: {
            'a': {
                position: {
                    name: 'layoutType',
                    args: {},
                }
            }
        },
        items: [
            // initialize 'rect' with port in group 'a'
            {
                group: 'a',
                args: {} // overrides `args` from the group level definition.
            },
            // ... other ports
        ]
    }
});

// ....
// add another port to group 'a'.
rect.addPort({ group:'a' });

Pre-defined layouts:

On sides

A simple layout suitable for rectangular shapes. It evenly spreads ports along a single side.

name string Can be either left, right, top, bottom.
args object
x number Overrides the x value calculated by the layout function
y number Overrides the y value calculated by the layout function
dx number Added to the x value calculated by the layout function
dy number Added to the y value calculated by the layout function
angle number The port rotation angle.
{
    name: 'left',
    args: {
        x: 10,
        y: 10,
        angle: 30,
        dx: 1,
        dy: 1
    }
}

Line

A layout which evenly spreads ports along a line defined by a start and en end point.

name string line
args object
start { x:number, y:number } The line starting point
end { x:number, y:number } The line end point
{
    name: 'line',
    args: {
        start: { x: 10, y: 10 },
        end: { x: 20, y: 50 }
    }
}

Absolute

It lay a port out at the given position (defined as a x, y coordinates or percentage of the element dimensions).

name string absolute
args object
x number | string Sets the port's x coordinate. Can be defined as a percentage string ('50%') or as a number
y number | string Sets the port's y coordinate. Can be defined as a percentage string ('50%') or as a number
angle number The port rotation angle.
{
    name: 'absolute',
    args: {
        x: '10%',
        y: 10,
        angle: 45
    }
}

Radial

Suitable for circular shapes. The ellipseSpreads evenly spreads ports along an ellipse. The ellipse spreads ports from the point at startAngle leaving gaps between ports equal to step.

name string Can be either ellipse, ellipseSpread.
args object
x number Overrides the x value calculated by the layout function
y number Overrides the y value calculated by the layout function
dx number Added to the x value calculated by the layout function
dy number Added to the y value calculated by the layout function
dr number Added to the port delta rotation
startAngle number Default value is 0.
step number Default 360 / portsCount for the ellipseSpread, 20 for the ellipse
compensateRotation boolean set compensateRotation:true when you need to have ports in the same angle as an ellipse tangent at the port position.
{
    name: 'ellipseSpread',
    args: {
        dx: 1,
        dy: 1,
        dr: 1,
        startAngle: 10,
        step: 10,
        compensateRotation: false
    }
}

Custom layout

An alternative for built-in layouts is providing a function directly, where the function returns an array of port positions.

/**
* @param {Array<object>} portsArgs
* @param {g.Rect} elBBox shape's bounding box
* @param {object} opt Group options
* @returns {Array<g.Point>}
*/
function(portsArgs, elBBox, opt) {

    // ports on sinusoid
    return _.map(portsArgs, function(portArgs, index) {

        var step = -Math.PI / 8;
        var y = Math.sin(index * step) * 50;
        return g.point({ x: index * 12, y: y + elBBox.height });
    });
}

Port layouts demo

layout.PortLabel

Port label layout functions calculate port label positions relatively to port positions.

Pre-defined port label layouts

On Sides

Simple label layout suitable for rectangular shapes. It places the label on arbitrary side of a port.

name string Can be either left, right, bottom, top.
args object | string
x number Overrides the x value calculated by the layout function
y number Overrides the y value calculated by the layout function
angle number The port label rotation angle.
attrs number JointJS style attribute applied on label's DOM element and it's children. The same notation as the attrs property on Element.
label: {
    position: {
        name : 'right',
        args: {
            x: 0,
            y: 0,
            angle: 0,
            attrs: {}
        }
    }
}

Inside/Outside

Places the label inside or outside of a rectangular shape. Where 'oriented' versions rotate the text towards the element center.

name string Can be either inside, outside, insideOriented, outsideOriented.
args object | string
offset number Offset in direction from the shape's center.
attrs number JointJS style attribute applied on label's DOM element and it's children. The same notation as the attrs property on Element.

label: {
    position: {
        name :'outsideOriented',
        args: {
            offset: 10,
            attrs: {}
    }
}

Radial

Places the label outside of a circular shape. Where the 'oriented' version rotates the text towards the element center.

name string Can be either radial, radialOriented.
args object | string
offset number Offset in direction from the shape's center.
attrs number JointJS style attribute applied on label's DOM element and it's children. The same notation as the attrs property on Element.
label: {
    position: {
        name :'radialOriented',
        args: {
            offset: 0,
            attrs: {}
        }
    }
}

Manual placement

It allows to set a label position directly.

name string manual
args object | string
x number Sets the label's x coordinate.
y number Sets the label's y coordinate.
angle number The port label rotation angle.
attrs number JointJS style attribute applied on label's DOM element and it's children. The same notation as the attrs property on Element.
label: {
    position: {
        name: 'manual',
        args: {
            x: 10,
            y: 20,
            angle: 45,
            attrs: {}
        }
    }
}

Port label layout demo

linkTools

A link tool is a view that renders a certain type of control elements on top of the LinkView it is attached to; for example the Vertices tool creates an interactive handle above every vertex (these handles then allow the user to move and/or delete each vertex). Link tools all inherit from the joint.dia.ToolView class. A collection of tools is added to a ToolsView; a tools view is then added to the linkView with the linkView.addTools() function.

The JointJS library comes with a collection of pre-made link tool definitions in the joint.linkTools namespace:

To create a new link tool, we call its constructor. Example:

var verticesTool = new joint.linkTools.Vertices({
    snapRadius: 10
});

In addition, the joint.linkTools namespace contains a customizable button class:

Example:

var infoTool = new joint.linkTools.Button({
    markup: [{
        tagName: 'circle',
        selector: 'button',
        attributes: {
            'r': 7,
            'fill': '#001DFF',
            'cursor': 'pointer'
        }
    }, {
        tagName: 'path',
        selector: 'icon',
        attributes: {
            'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
            'fill': 'none',
            'stroke': '#FFFFFF',
            'stroke-width': 2,
            'pointer-events': 'none'
        }
    }],
    distance: 60,
    offset: 0,
    action: function(evt) {
        alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
    }
});

All of the built-in link tools accept the following optional argument, in addition to their own arguments:

focusOpacity number What should be the opacity of the tool when it is focused (e.g. with the toolView.focus function)? Default is undefined, meaning that the tool's opacity is kept unchanged.

Example:

var verticesTool = new joint.linkTools.Vertices({
    focusOpacity: 0.5
});

linkTools.Boundary

The Boundary link tool renders a rectangular border to show the bounding box of the link. It accepts one additional argument, which can be passed as an object to the link tool constructor:

padding number This option determines whether the boundary area should be visually inflated and if so, by how much. Default is 10.

Example:

var boundaryTool = new joint.linkTools.Boundary({
    focusOpacity: 0.5,
    padding: 20
});

linkTools.Button

The Button link tool allows you to have a custom button rendered at a given position along the link. It accepts five additional arguments, which can be passed as an object to the link tool constructor:

distance number Distance at which the button should be placed. Negative numbers are accepted; then the distance is counted from the end of the link. Default is 0.
string Percentage strings (e.g. '40%') are also accepted.
rotate boolean Should the button rotate according to the slope of the link at the position specified by distance? Default is false.
offset number Relative offset of the button from the link. Positive numbers mean that the button should be offset to the right of the link (relative to the direction from source to target); negative numbers mean that the button should be offset to the left of the link (relative to the direction from source to target). Default is 0.
action function What should happen when the user clicks the remove button? Default is undefined (no interaction).

The callback function is expected to have the signature function(evt) where evt is a jQuery.Event object. The button view is available inside the function as this; the button model is available as this.model.
markup JSONMarkup The markup of the button, provided in the JointJS JSON format. Default is undefined (no content).

Example of a useful custom info button:

var infoButton = new joint.linkTools.Button({
    focusOpacity: 0.5,
    distance: 60,
    action: function(evt) {
        alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
    },
    markup: [{
        tagName: 'circle',
        selector: 'button',
        attributes: {
            'r': 7,
            'fill': '#001DFF',
            'cursor': 'pointer'
        }
    }, {
        tagName: 'path',
        selector: 'icon',
        attributes: {
            'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
            'fill': 'none',
            'stroke': '#FFFFFF',
            'stroke-width': 2,
            'pointer-events': 'none'
        }
    }]
});

The linkTools.Button class can also be extended, to create a reusable custom button type within the joint.linkTools namespace. Then, a new instance of the custom button type can be obtained by calling its constructor:

joint.linkTools.InfoButton = joint.linkTools.Button.extend({
    name: 'info-button',
    options: {
        focusOpacity: 0.5,
        distance: 60,
        action: function(evt) {
            alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
        },
        markup: [{
            tagName: 'circle',
            selector: 'button',
            attributes: {
                'r': 7,
                'fill': '#001DFF',
                'cursor': 'pointer'
            }
        }, {
            tagName: 'path',
            selector: 'icon',
            attributes: {
                'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
                'fill': 'none',
                'stroke': '#FFFFFF',
                'stroke-width': 2,
                'pointer-events': 'none'
            }
        }]
    }
});

var infoButton = new joint.linkTools.InfoButton();

linkTools.Remove

The Remove link tool renders a remove button at a given position along the link. It accepts five additional arguments, which can be passed as an object to the link tool constructor:

distance number Distance at which the button should be placed. Negative numbers are accepted; then the distance is counted from the end of the link. Default is 60.
string Percentage strings (e.g. '40%') are also accepted.
rotate boolean Should the button rotate according to the slope of the link at the position specified by distance? Default is false.
offset number Relative offset of the button from the link. Positive numbers mean that the button should be offset to the right of the link (relative to the direction from source to target); negative numbers mean that the button should be offset to the left of the link (relative to the direction from source to target). Default is 0.
action function What should happen when the user clicks the remove button? Default:
function(evt) {
    this.model.remove({ ui: true, tool: this.cid });
}
The callback function is expected to have the signature function(evt) where evt is a jQuery.Event object. The button view is available inside the function as this; the button model is available as this.model.

markup JSONMarkup The markup of the button, provided in the JointJS JSON format. Default:
[{
    tagName: 'circle',
    selector: 'button',
    attributes: {
        'r': 7,
        'fill': '#FF1D00',
        'cursor': 'pointer'
    }
}, {
    tagName: 'path',
    selector: 'icon',
    attributes: {
        'd': 'M -3 -3 3 3 M -3 3 3 -3',
        'fill': 'none',
        'stroke': '#FFFFFF',
        'stroke-width': 2,
        'pointer-events': 'none'
    }
}]

Example:

var removeButton = new joint.linkTools.Remove({
    focusOpacity: 0.5,
    rotate: true,
    distance: -20,
    offset: 20
});

linkTools.Segments

The Segments link tool renders handles above all segments of the link (as determined by the link connector). It accepts four additional arguments, which can be passed as an object to the link tool constructor:

redundancyRemoval boolean If the user arranges two (or more) segments so that they lie on a single line, should the middle one(s) be considered redundant and removed? Default is true. Note that this setting is not applied until the user actually moves one of the segments in question; this means that segments can still be arranged in this redundant fashion, using the