Skip to main content

Link

The basic model for diagram links. It inherits from joint.dia.Cell with a few additional properties and methods specific to links. For a quick introduction to links, see our tutorial. To learn about the elements and their features in detail, see the links learn section.

Methods​

appendLabel()​

link.appendLabel(label [, opt])

Add a new label at the end of the labels array.

connector()​

link.connector()

Return a shallow copy of the connector property of the link.

link.connector(connector [, opt])

Set the connector of the link.

If the connector argument is an object, it is expected to have the form { name: connectorName, args?: connectorArgs }. Here connectorName is expected to match either the name of a built-in connector or the name of a custom connector.

If the connector argument is a function, it is expected to define a custom connector with the signature function(sourcePoint, targetPoint, vertices, connectorArgs, linkView) that returns a string representing the SVG path data that will be used to render the link.

link.connector(connectorName [, connectorArgs, opt])

Set the connector of the link to have the value { name: connectorName, args: connectorArgs }.

The connectorName string is expected to match either the name of a built-in connector or the name of a custom connector. The connectorArgs parameter is optional.

disconnect()​

link.disconnect()

Disconnect the link from its source and target elements. The source and target then become a point at [0,0].

getBBox()​

link.getBBox()

Return the bounding box of the link model, represented as a g.Rect.

This method creates the bounding box from the link polyline (see the link.getPolyline function). This simplified heuristic may cause portions of curved links to protrude out of the reported bounding box. See the documentation of the linkView.getBBox function for details about the differences.

getPolyline()​

link.getPolyline()

Return a polyline that approximates the shape of the link. The polyline is created from the two link endpoints, with link vertices in between.

getSourceCell()​

link.getSourceCell()

Return the source cell (element or link) of the link, or null if the element's source is a point.

getSourceElement()​

link.getSourceElement()

Return the source element of the link or null if there is none.

getSourcePoint()​

link.getSourcePoint()

Return the source point of the link.

  • If the link endpoint is pinned to a specific point on the paper, return that point.
  • If the link is connected to another link, return the midpoint of that link's polyline.
  • If the link is connected to a port on an element, return the center of that port.
  • If the link is connected to an element, return the center of that element.

getTargetCell()​

link.getTargetCell()

Return the target cell (element or link) of the link, or null if the element's target is a point.

getTargetElement()​

link.getTargetElement()

Return the target element of the link or null if there is none.

getTargetPoint()​

link.getTargetPoint()

Return the target point of the link.

  • If the link endpoint is pinned to a specific point on the paper, return that point.
  • If the link is connected to another link, return the midpoint of that link's polyline.
  • If the link is connected to a port on an element, return the center of that port.
  • If the link is connected to an element, return the center of that element.

hasLabels()​

link.hasLabels()

Return true if the link has at least one label. Return false otherwise.

hasLoop()​

link.hasLoop([opt])

Return true if this link is a loop link. In a loop link source and target are equal.

If opt.deep is true, the notion of a loop link is extended to a deep hierarchy. For example, if the link connects a parent element with one of its embedded elements, the link is considered a loop link, as well.

insertLabel()​

link.insertLabel(index, label [, opt])

Add a new label at index. Pass index -1 to add the label at the end of the labels array.

insertVertex()​

link.insertVertex(index, vertex [, opt])

Add a new vertex at index. Pass index -1 to add the vertex at the end of the vertices array.

isElement()​

link.isElement()

Always returns false. See cell.isElement().

link.isLink()

Always returns true. See cell.isLink().

label()​

link.label(index)

Return the label at index.

link.label(index, properties [, opt])

Update properties of the label at index. By default, the new properties are merged into the old ones; pass the { rewrite: true } option along to disregard old properties.

Example usage:

link.label(0, {
    markup: [
        {
            tagName: 'rect',
            selector: 'body'
        }, {
            tagName: 'text',
            selector: 'label'
        }
    ],
    attrs: {
        body: {
            fill: 'white' // white background
        },
        label: {
            text: 'my label', // text to show
            fill: 'blue' // blue text
        }
    },
    position: {
        distance: 0.5, // midway on the connection path
        offset: {
            x: 10, // 10 local x units to the right
            y: -5 // 5 local y units above
        },
        angle: 45, // rotate by 45 degrees clockwise
        args: {
            keepGradient: true, // auto-rotate by path slope at distance
            ensureLegibility: true // auto-rotate label if upside-down
        }
    }
});

Note that all labels are stored in an array on the link model under the attribute labels. Use the link.labels function to access the array.

labels()​

link.labels()

Return a shallow copy of labels array.

link.labels(labelsArray [, opt])

Set array of labels on the link.

removeLabel()​

link.removeLabel(index [, opt])

Remove label at index. Pass index -1 to remove the last label of the labels array.

removeVertex()​

link.removeVertex(index [, opt])

Remove vertex at index. Pass index -1 to remove the last vertex of the vertices array.

reparent()​

link.reparent()

Automatically find and set the best parent element for the link so that when the parent element is moved, the link and all its vertices are moved too. The best parent is determined as the common ancestor of the source and target elements of the link. Useful for hierarchical diagrams. See the Devs demo on how this can be used.

router()​

link.router()

Return a shallow copy of the router property of the link.

link.router(router [, opt])

Set the router of the link.

If the router argument is an object, it is expected to have the form { name: routerName, args?: routerArgs }. Here routerName is expected to match either the name of a built-in router or the name of a custom router.

If the router argument is a function, it is expected to define a custom router with the signature function(vertices, routerArgs, linkView) that returns an array of route points.

link.router(routerName [, routerArgs, opt])

Set the router of the link to have the value { name: routerName, args: routerArgs }.

The routerName string is expected to match either the name of a built-in router or the name of a custom router. The routerArgs parameter is optional.

scale()​

link.scale(sx, sy, origin [, opt])

Scales the link's points (vertices) relative to the given origin.

source()​

link.source()

Return a shallow copy of the source property of the link.

If the beginning of the link is connected to an element, an object in the format { id: elementID } is returned. If the beginning of the link is specified as a point instead (the link is pinned to the paper at that point), an object in the format { x: sourceX, y: sourceY } is returned. Furthermore, any additional arguments of the source are returned alongside those properties.

If you need to be sure that a Cell is returned (and not a Point), use the link.getSourceCell function instead. If you need an Element, use the link.getSourceElement function.

link.source(source [, opt])

Set the source of the link.

If the link is to be connected to an element, send an object in the format { id: element.id } (or a joint.dia.Element object). If the link is to be pinned to the paper, send an object in the format { x: sourceX, y: sourceY } (or a g.Point object).

link.source(rect);
link.source({ id: rect.id });

link.source(new g.Point(100, 100));
link.source({ x: 100, y: 100 });

Additional options may by provided to further specify the behavior of link at the source:

link.source(rect, {
    selector: 'body',
    anchor: {
        name: 'bottomLeft',
        args: {
            dx: 20,
            dy: -10
        }
    }
});

More information can be found in link source documentation.

target()​

link.target()

Return a shallow copy of the target property of the link.

If the ending of the link is connected to an element, an object in the format { id: elementID } is returned. If the ending of the link is specified as a point instead (the link is pinned to the paper at that point), an object in the format { x: targetX, y: targetY } is returned. Furthermore, any additional arguments of the target are returned alongside those properties.

If you need to be sure that a Cell is returned (and not a Point), use the link.getTargetCell function instead. If you need an Element, use the link.getTargetElement function.

link.target(target [, opt])

Set the target of the link.

If the link is to be connected to an element, send an object in the format { id: element.id } (or a joint.dia.Element object). If the link is to be pinned to the paper, send an object in the format { x: targetX, y: targetY } (or a g.Point object).

link.target(rect);
link.target({ id: rect.id });

link.target(new g.Point(100, 100));
link.target({ x: 100, y: 100 });

Additional options may by provided to further specify the behavior of link at the target:

link.target(rect, {
    selector: 'body',
    anchor: {
        name: 'bottomLeft',
        args: {
            dx: 20,
            dy: -10
        }
    }
});

More information can be found in link target documentation.

translate()​

link.translate(tx, ty [, opt])

Translate the link vertices (and source and target if they are points) by tx pixels in the x-axis and ty pixels in the y-axis.

If opt object is passed, it can contain data that is passed over the the event listeners for the change event on the link or graph.

vertex()​

link.vertex(index)

Return the vertex at index.

link.vertex(index, vertex [, opt])

Update the vertex at index with value of vertex. By default the new value is merged into the old value. Pass the { rewrite: true } option along to disregard the old value.

A vertex has only two properties, x and y. It may be defined as a g.Point object.

Example vertex:

link.vertex(0, {
    x: 100,
    y: 200
});

Note that all vertices are stored in an array on the link model under the attribute vertices. Use the link.vertices function to access the array.

vertices()​

link.vertices()

Return a shallow copy of vertices array.

link.vertices(verticesArray [, opt])

Set array of vertices on the link.

Events​

The following list contains events that you can react on:

change​

changegeneric event triggered for any change on the link
change:attrstriggered when the link changes its attributes
change:connectortriggered when the link changes its connector
change:routertriggered when the link changes its router
change:sourcetriggered when the link changes its source
change:targettriggered when the link changes its target
change:verticestriggered when the link changes its vertices array
change:ztriggered when the link is moved in the z-level (toFront and toBack)
link.on('change:source', function() { alert('source of the link changed') })

transition​

transition:starttriggered when a transition starts
transition:endtriggered when a transition ends

Stay in the know

Be where thousands of diagramming enthusiasts meet

Star us on GitHub