Delta 5 - Connectors

Lines between shapes provide valuable information in many diagrams

Overview

Connections between elements are a key part of diagrams, where they can represent data flow, dependencies, or other associations. In svgdx connectors link together a start and end element, and use auto-styles to provide visual information such as directionality.

Simple Connectors

Given two elements with unique id attributes, a connection between them may be created using the <line> or <polyline> element with start and end attributes of the relevant id references:

<svg>
  <rect id="a" wh="20 10" text="input" />
  <rect id="b" xy="^|h 10" wh="^" text="output" />

  <line start="#a" end="#b"/>
</svg>

In this simple form, a straight line between the two connected shapes is always drawn. If only base element references (i.e. #abc) are given for the start and end points, the location the line is drawn from is calculated automatically based on the shortest connection:

<svg>
  <rect id="a" wh="20 10" text="input" />
  <rect id="b" xy="^ 25" wh="^" text="output" />

  <line start="#a" end="#b"/>
</svg>

This can result in connectors which don’t look great, e.g. the following is not particularly pleasing:

<svg>
  <rect id="a" wh="20 10" text="input" />
  <rect id="b" xy="^ 20" wh="^" text="output" />

  <line start="#a" end="#b"/>
</svg>

If you still want automatic placement but only want the cardinal face centres (t, r, b, l) to be considered, add connect="cardinal":

<svg>
  <rect id="a" wh="20 10" text="input" />
  <rect id="b" xy="^ 20" wh="^" text="output" />

  <line start="#a" end="#b" connect="cardinal"/>
</svg>

For straight line connectors, the default mode prefers overlap-aware edge midpoints and then corners. For elbow connectors created from <polyline>, cardinal faces are already the default; connect is most useful when you want <line> to follow the same target-selection rule.

To counter this, provide more explicit start and(/or) end references, e.g. using explicit locations or edge-specs.

<svg>
  <rect id="a" wh="20 10" text="input" />
  <rect id="b" xy="^ 20" wh="^" text="output" />

  <line start="#a@r" end="#b@t"/>
</svg>

Providing an “edgespec”, which consists of one of the edges (t for top, r right, b bottom, or l for left) followed by a colon and a percentage or offset - for example #abc@r:25% - can be particularly useful when multiple connections would otherwise target the same point:

<svg>
  <rect id="a" wh="10" text="a" />
  <rect id="b" xy="^|h 5" wh="10" text="b" />
  <rect id="c" xy="^|h 5" wh="10" text="c" />
  <rect id="d" xy="^|v 5" wh="10" text="d" />
  <rect id="z" xy="#b|v 20" wh="10" text="z" />

  <line start="#a" end="#z@t:20%"/>
  <line start="#b" end="#z@t:40%"/>
  <line start="#c" end="#z@t:60%"/>
  <line start="#d" end="#z@t:80%"/>
</svg>

Connector styles

Classes can be applied to connector elements which control the style. Note these are not restricted to connectors, but this is their primary use-case. As with classes in general, these can be combined as appropriate.

Polyline connectors

Connectors can be defined by the <polyline> SVG element in addition to <line>. With polylines, connectors are restricted to horizontal and vertical segments, with corners at appropriate places.

Note that with the polyline case, the start and end specs don’t need the full locspec (i.e. @r, @l), as corner locations are not included when evaluating default join points on elements.

By default, corners happen 50% along the path between the connected elements, but this can be overwritten with the corner-offset attribute.

For elbow connectors such as the above, the corner-offset can be given as either a percentage or an absolute value. If the connector is joining things facing the same direction, it requires an absolute value, which is 3 units by default.

End gaps

Providing a small gap between a connector and the objects it is connecting may improve the look of the generated output. This can be achieved using the gap attribute on connectors. This takes either one or a pair of length values (absolute, %age, or a rational fraction). If two values are provided, they apply to the start and end of the connector respectively; if a single value is given it applies to both.

Relative (%age and fraction) values relate to the total connector length (including all segments of an elbow connector); if the combined start and end values exceed 100%, the connector will become invisible.

<svg>
  <rect id="a" wh="10 30" text="a" />
  <rect id="b" xy="30 0" wh="10 30" text="b" />
  <rect id="c" xy="60 0" wh="10 50" text="c" />
  <rect id="d" xy="0 40" wh="40 10" text="d" />

  <line start="#a@r:10%" end="#b"/>
  <line start="#a@r:30%" end="#b" gap="2" class="d-arrow"/>
  <line start="#a@r:50%" end="#b" gap="1 5"/>
  <line start="#a@r:70%" end="#b" gap="60% 10%"/>
  <line start="#a@r:90%" end="#b" gap="5%"/>

  <line start="#b@r:10%" end="#c@l:10%"/>
  <line start="#b@r:30%" end="#c@l:30%" gap="2" />
  <line start="#b@r:50%" end="#c@l:50%" gap="1 5" class="d-biarrow"/>
  <line start="#b@r:70%" end="#c@l:70%" gap="60% 10%" class="d-arrow"/>
  <line start="#b@r:90%" end="#c@l:90%" gap="5%"/>

  <polyline start="#a" end="#d@t:40%" gap="7%" class="d-arrow"/>
  <polyline start="#b" end="#d@t:60%" gap="5% 15%"/>
</svg>