The basic model for diagram links. It inherits from joint.dia.Cell with a few additional properties and methods specific to links.

Links have two crucial attributes: `source` and `target`. They define the starting point and the end point of the link. They can be defined as an element id or as a Point:

    var link1 = new joint.dia.Link({
        source: { id: sourceId },
        target: { id: targetId, port: portId }
    });

    var link2 = new joint.dia.Link({
        source: { id: sourceId },
        target: { x: 100, y: 100 }
    });

These are not the only attributes that may be specified for a newly-created `joint.dia.Link`, however. An individual link instance may provide a value for these attributes:

- `markup` - provide custom link markup. May be specified as an XML string or JSON array.
- `attrs` - provide custom link attributes. These allow you to change the style and size of SVG elements, identified by their selectors.
- `vertices` - provide an array of vertices.
- `vertexMarkup` - provide custom vertex markup (on hover).
- `toolMarkup` - provide custom tool markup (on hover).
- `doubleToolMarkup` - provide custom markup for second set of tools (on hover, if `linkView.doubleLinkTools` is `true`).
- `arrowheadMarkup` - provide custom arrowhead markup (on hover).
- `labels` - provide an array of labels. Each can have its own markup, position, and attrs specified.

It is also possible to pass custom attributes to the link. These may be useful to identify an individual link model for the purposes of linkView interaction (see `LinkView` documentation for more information). For example, to only enable custom contextmenu interaction for `link1` but not `link2`:

    var CustomLinkView = joint.dia.LinkView.extend({
        contextmenu: function(evt, x, y) {
            if (this.model.get('customLinkInteractions')) {
                // only links with `customLinkInteractions: true`
                this.addLabel(x, y);
            }
        }
    });

    var paper = new joint.dia.Paper({
        //...
        linkView: CustomLinkView,
        interactive: function(cellView) {
            if (cellView.model.get('customLinkInteractions')) {
                // only links with `customLinkInteractions: true`
                return { vertexAdd: false };
            }
            return true; // otherwise
        }
    });

    var link1 = new joint.dia.Link({
        //...
        customLinkInteractions: true // right-click adds a label
    });

    var link2 = new joint.dia.Link({
        //...
        customLinkInteractions: false // or omit completely
    });

#### Custom Link

It is possible to extend the `joint.dia.Link` class to create a custom link. A custom link may override Link properties to assign its own defaults. These values override builtin defaults, if provided, and are applied to all instances of the new Link type, unless an individual instance overrides them with its own values. The following Link attributes are applicable in this context:

- `markup` - provide default link markup for all instances of this Link type. May be specified as an XML string or JSON array.
- `attrs` - provide default link attributes for all instances of this Link type. These allow you to change the style and size of SVG elements, identified by their selectors.
- `vertexMarkup` - provide default vertex markup for all vertices created on an instance of this Link type (on hover).
- `toolMarkup` - provide custom tool markup for all instances of this Link type (on hover).
- `doubleToolMarkup` - provide custom markup for second set of tools for all instances of this Link type (on hover, if `linkView.doubleLinkTools` is `true`).
- `arrowheadMarkup` - provide custom arrowhead markup for all instances of this Link type (on hover).
- `defaultLabel` - provide default properties (markup, attrs, position) for all labels created on an instance of this Link type.

The values of these defaults may be important; the `linkView.addLabel()` shortcut function is only capable of adding default labels to the link.

Example:

    var CustomLink = joint.dia.Link.define('examples.CustomLink', {
        defaultLabel: {
            markup: [
                {
                    tagName: 'circle',
                    selector: 'body'
                }, {
                    tagName: 'text',
                    selector: 'label'
                }
            ],
            attrs: {
                label: {
                    text: '%', // default label text
                    fill: '#ff0000', // default text color
                    fontSize: 14,
                    textAnchor: 'middle',
                    yAlignment: 'middle',
                    pointerEvents: 'none'
                },
                body: {
                    ref: 'label',
                    fill: '#ffffff',
                    stroke: '#000000',
                    strokeWidth: 1,
                    refR: 1,
                    refCx: 0,
                    refCy: 0
                }
            },
            position: {
                distance: 0.5, // place label at midpoint by default
                offset: {
                    y: -20 // offset label by 20px upwards by default
                },
                args: {
                    absoluteOffset: true // keep offset absolute when moving by default
                }
            }
        }
    });

    var link = new CustomLink({
        //...
    });

#### Builtin Default Attributes

To ensure backwards compatibility, the `joint.dia.Link` class comes with a private builtin `defaultLabel` attribute. It is reproduced here for reference:

    defaultLabel: {
        // builtin default markup:
        // used if neither defaultLabel.markup
        // nor label.markup is set
        markup: [
            {
                tagName: 'rect',
                selector: 'rect'
            }, {
                tagName: 'text',
                selector: 'text'
            }
        ],
        // builtin default attributes:
        // applied only if builtin default markup is used
        attrs: {
            text: {
                fill: '#000000',
                fontSize: 14,
                textAnchor: 'middle',
                yAlignment: 'middle',
                pointerEvents: 'none'
            },
            rect: {
                ref: 'text',
                fill: '#ffffff',
                rx: 3,
                ry: 3,
                refWidth: 1,
                refHeight: 1,
                refX: 0,
                refY: 0
            }
        },
        // builtin default position:
        // used if neither defaultLabel.position
        // nor label.position is set
        position: {
            distance: 0.5
        }
    }

If custom `position` object is not provided (neither as a type default nor as an instance value), builtin default label position is applied instead (`{ distance: 0.5 }`).

Furthermore, if custom `markup` is not provided (neither as a type default nor as an instance value), builtin default label markup is applied, alongside the builtin default label attrs object. However, it is very highly recommended that you provide both your own `markup` and your own `attrs` - unless you want to use the builtin default precisely as-is.