# Blazor Diagram Connections

The Connections in the Telerik Diagram for Blazor signify the relationship between two Shapes (graph nodes). This article describes all Diagram Connection customization options.

## Basics

A Connection is a link that shows a relationship between two Diagram Shapes. A Connection can also span across points with specific coordinates, with no associated Shapes.

The fundamental settings of the Telerik Diagram Connections (`<DiagramConnection>`) include:

* The `FromId` and `ToId` parameters must match the associated [Shape `Id`s](https://www.telerik.com/blazor-ui/documentation/components/diagram/shapes#basics). You can also define a Connection that does not link Shapes. In this case, use the `X` and `Y` parameters of the child tags `<DiagramConnectionFrom>` and `<DiagramConnectionTo>`.
* The [Connection `Type`](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#connection-types) determines the Connection route and route angles.
* The Connection [cap `Type`](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#cap-types) determines whether the Connections appear directed or undirected.
* The `Selectable` parameter of `<DiagramConnectionDefaults>` sets if Connections can be selected, which determines the ability to [drag or remove](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#editability) them.
* `Text` defines the Connection label. Use the child `<DiagramConnectionContent>` tag to set it.

> caption Using Basic Connection Parameters

```RAZOR.skip-repl
<DiagramConnection FromId="shape1" ToId="shape2">
    <DiagramConnectionContent Text="1 to 2" />
</DiagramConnection>
```

> caption Using Connections without Shapes

```RAZOR.skip-repl
<DiagramConnection>
    <DiagramConnectionFrom X="50" Y="100" />
    <DiagramConnectionTo X="150" Y="200" />
</DiagramConnection>
```

In addition to the above, you can use the `DataItem` Connection parameter to provide an object with additional values to be used in a [visual function](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#visual-function).

## Connection Types

The available Diagram Connection types include:

* `Cascading` (default)—Connections display as rectangular routes with one or more right angles. The cascading Connection type is suitable for [tree Diagram layouts](https://www.telerik.com/blazor-ui/documentation/components/diagram/layouts#tree-layout), as the Connections enhance the representation of a hierarchy.
* `Polyline`—Connections display as polylines that connect the related Shapes and all intermediate points. If [Connection points](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#connection-points) are not defined, then the Connection displays as a straight line.

> caption Setting Connection Type Globally

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramConnectionDefaults Type="@DiagramConnectionType.Polyline" />
</TelerikDiagram>
```

> caption Setting Type per Connection

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramConnections>
        <DiagramConnection Type="@DiagramConnectionType.Cascading" />
    </DiagramConnections>
</TelerikDiagram>
```

### Connection Points

[`Polyline` Connections](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#connection-types) can pass through multiple points at specific coordinates, no matter if the Connections link Shapes or not.

> caption Using Connection Points

<demo metaUrl="client/diagram/connections/connection-points-5/" height="450"></demo>

## Cap Types

The link between two Diagram Shapes is always defined through the `FromId` and `ToId` parameters of the `<DiagramConnection>` tag. From this point of view, a Diagram Connection is always directed. However, you can configure the Connections to appear bi-directional or non-directional.

The available cap types are the members of the `DiagramConnectionsStartCapType` and `DiagramConnectionsEndCapType` enums:

* `ArrowEnd`—the cap arrow points away from the Connection, towards the Shape
* `FilledCircle` (default)
* `None`

The configure cap types globally for all Connections, use the `Type` parameter of `<DiagramConnectionDefaultsStartCap>` and `<DiagramConnectionDefaultsEndCap>`. To configure the cap types of a specific Connection, use the `Type` parameter of `<DiagramConnectionStartCap>` and `<DiagramConnectionEndCap>`.

Note the difference between caps and selection handles:

* The caps are visible when a Connection is not selected.
* The selection handles are visible when a Connection is selected (clicked).

> caption Setting global and Connection-specific cap types

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramConnectionDefaults>
        <DiagramConnectionDefaultsEndCap Type="@DiagramConnectionsEndCapType.ArrowEnd" />
        <DiagramConnectionDefaultsStartCap Type="@DiagramConnectionsStartCapType.ArrowEnd" />
    </DiagramConnectionDefaults>

    <DiagramConnections>
        <DiagramConnection>
            <DiagramConnectionEndCap Type="@DiagramConnectionsEndCapType.FilledCircle" />
            <DiagramConnectionStartCap Type="@DiagramConnectionsStartCapType.FilledCircle" />
        </DiagramConnection>
    </DiagramConnections>
</TelerikDiagram>
```

## Connection Text

The Diagram allows you to display text labels on Connections and control their position and offset from the Connection path. You can configure the text content, color, and precise positioning relative to the Connection.

The text positioning is controlled by two parameters:

* `Offset`—the distance in pixels between the label and the Connection path
* Position settings that use the following enums:
  * `DiagramConnectionsContentPositionHorizontal`—`Left` or `Right`
  * `DiagramConnectionsContentPositionVertical`—`Top` or `Bottom`

To configure Connection text globally for all Connections, use the `Text`, `Color`, and `Offset` parameters of `<DiagramConnectionDefaultsContent>`, and the `Horizontal` and `Vertical` parameters of `<DiagramConnectionDefaultsContentPosition>`.

To configure the text for a specific Connection, use the `Text`, `Color`, and `Offset` parameters of `<DiagramConnectionContent>`, and the `Horizontal` and `Vertical` parameters of `<DiagramConnectionContentPosition>`.

> caption Setting Connection text with positioning

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramConnections>
        <DiagramConnection FromId="1" ToId="2">
            <DiagramConnectionStroke />
            <DiagramConnectionContent Text="Connection 1" Color="red" Offset="16">
                <DiagramConnectionContentPosition Vertical="@DiagramConnectionsContentPositionVertical.Bottom"
                                                  Horizontal="@DiagramConnectionsContentPositionHorizontal.Right" />
            </DiagramConnectionContent>
        </DiagramConnection>

        <DiagramConnection FromId="3" ToId="1">
            <DiagramConnectionStroke />
            <DiagramConnectionContent Text="Connection 3" Color="blue" Offset="10">
                <DiagramConnectionContentPosition Vertical="@DiagramConnectionsContentPositionVertical.Top"
                                                  Horizontal="@DiagramConnectionsContentPositionHorizontal.Left" />
            </DiagramConnectionContent>
        </DiagramConnection>
    </DiagramConnections>
</TelerikDiagram>
```

## Tooltips

The Diagram allows you to display tooltips when hovering over Connections. Each Connection requires explicit tooltip content configuration through the `Template` parameter.

The available tooltip parameters are:

* `Visible` (bool, default: `false`)—controls whether the tooltip is displayed on hover
* `Class` (string)—applies a custom CSS class to the tooltip for styling
* `Template` (RenderFragment)—defines the custom content to display in the tooltip

> caption Configuring Connection tooltips

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramShapes>
        <DiagramShape Id="shape1">
            <DiagramShapeContent Text="Shape 1" />
        </DiagramShape>
        <DiagramShape Id="shape2">
            <DiagramShapeContent Text="Shape 2" />
        </DiagramShape>
    </DiagramShapes>

    <DiagramConnections>
        <DiagramConnection Id="connection1" FromId="shape1" ToId="shape2">
            <DiagramConnectionStroke Color="red" />
            <DiagramConnectionContent Text="Connection 1" Color="ff0000" Offset="16">
                <DiagramConnectionContentPosition Vertical="@DiagramConnectionsContentPositionVertical.Bottom"
                                                  Horizontal="@DiagramConnectionsContentPositionHorizontal.Right" />
            </DiagramConnectionContent>
            <DiagramConnectionTooltip Class="connection1" Visible="true">
                <Template>
                    <div>
                        id: 1
                    </div>
                </Template>
            </DiagramConnectionTooltip>
        </DiagramConnection>
    </DiagramConnections>
</TelerikDiagram>
```

## Selection Handles

Selection handles are the additional visual elements that appear at both ends of a Connection when it is selected (clicked). The handles appear on top of the [caps and connectors](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#diagram-elements).

> caption Configure selection handles globally and per Connection

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramConnectionDefaults>
        <DiagramConnectionDefaultsSelection>
            <DiagramConnectionDefaultsSelectionHandles Height="10" Width="10">
                <DiagramConnectionDefaultsSelectionHandlesFill Color="purple" />
                <DiagramConnectionDefaultsSelectionHandlesStroke Color="black" />
            </DiagramConnectionDefaultsSelectionHandles>
        </DiagramConnectionDefaultsSelection>
    </DiagramConnectionDefaults>

    <DiagramConnections>
        <DiagramConnection>
            <DiagramConnectionSelection>
                <DiagramConnectionSelectionHandles Height="16" Width="16">
                    <DiagramConnectionSelectionHandlesFill Color="lime" />
                    <DiagramConnectionSelectionHandlesStroke Color="green" />
                </DiagramConnectionSelectionHandles>
            </DiagramConnectionSelection>
        </DiagramConnection>
    </DiagramConnections>
</TelerikDiagram>
```

## Editability

By default, the Diagram allows users to:

* Drag a Connection by its start and end cap to link other Shapes than the current ones.
* Drag an entire Connection to reposition it while preserving its structure and shape endpoints.
* Remove the selected Connection(s).

To restrict these operations globally for all Connections, use the parameters of the `<DiagramConnectionDefaultsEditable>` tag.

To restrict operations for a specific Connection, use the parameters of the `<DiagramConnectionEditable>` tag.

Connection dragging and removing requires the `Selectable` parameter of `<DiagramConnectionDefaults>` to be set to `true`, which is by default.

To track dragging operations, handle the [`OnConnectionDragStart`](https://www.telerik.com/blazor-ui/documentation/components/diagram/events#onconnectiondragstart) and [`OnConnectionDragEnd`](https://www.telerik.com/blazor-ui/documentation/components/diagram/events#onconnectiondragend) events.

> caption Setting global and Connection-specific editing options

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramConnectionDefaults Selectable="true">
        <DiagramConnectionDefaultsEditable Drag="true" Remove="true" />
    </DiagramConnectionDefaults>

    <DiagramConnections>
        <DiagramConnection>
            <DiagramConnectionEditable Enabled="false" />
        </DiagramConnection>
    </DiagramConnections>
</TelerikDiagram>
```

### Resizable Connections

The Diagram allows users to reshape connections by dragging their intermediate [connection points](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#connection-points). To enable this functionality, use the `Points` child configuration of the editable settings.

* To enable editable connection points globally for all Connections, use the `<DiagramConnectionDefaultsEditablePoints>` tag inside `<DiagramConnectionDefaultsEditable>`.

* To enable editable connection points for a specific Connection, use the `<DiagramConnectionEditablePoints>` tag inside `<DiagramConnectionEditable>`.

> caption Enable editable connection points globally and per Connection

<demo metaUrl="client/diagram/connections/editable-points-4/" height="520"></demo>

## Styling

The following Connection styling options are available in child tags of `<DiagramConnectionDefaults>` and `<DiagramConnection>`:

* Text color and font properties, when using Connection content
* Background color (fill) for the Connection caps
* Background color (fill) for the default and hover states of the selection handles
* Border (stroke) color, type, and width for the caps and selection handles

> caption Setting global and Connection-specific color styles

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramConnectionDefaults>
        <DiagramConnectionDefaultsEndCap>
            <DiagramConnectionDefaultsEndCapFill Color="yellow" />
            <DiagramConnectionDefaultsEndCapStroke Color="red" />
        </DiagramConnectionDefaultsEndCap>
        <DiagramConnectionDefaultsStartCap>
            <DiagramConnectionDefaultsStartCapFill Color="yellow" />
            <DiagramConnectionDefaultsStartCapStroke Color="red" />
        </DiagramConnectionDefaultsStartCap>
        <DiagramConnectionDefaultsStroke Color="black" />
    </DiagramConnectionDefaults>

    <DiagramConnections>
        <DiagramConnection>
            <DiagramConnectionEndCap>
                <DiagramConnectionEndCapFill Color="lightblue" />
                <DiagramConnectionEndCapStroke Color="blue" />
            </DiagramConnectionEndCap>
            <DiagramConnectionStartCap>
                <DiagramConnectionStartCapFill Color="lightblue" />
                <DiagramConnectionStartCapStroke Color="blue" />
            </DiagramConnectionStartCap>
            <DiagramConnectionStroke Color="purple" />
        </DiagramConnection>
    </DiagramConnections>
</TelerikDiagram>
```

## Rich Content

Telerik UI for Blazor 15.0 adds the ability to declaratively enhance the default plain text content of Diagram Connections. The feature depends on child tags of `<DiagramConnectionContent>`. Refer to the API reference for details:

* [`<DiagramConnectionContentPadding>`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.diagramconnectioncontentpadding)
* [`<DiagramConnectionContentMargin>`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.diagramconnectioncontentmargin)
* [`<DiagramConnectionContentBlocks>`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.diagramconnectioncontentblocks)
* [`<DiagramConnectionContentBlockChildren>`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.diagramconnectioncontentblockchildren)
* [`<DiagramConnectionContentBlockChild>`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.diagramconnectioncontentblockchild)

Each block child can contain text or an image, depening on the block child's `Type`, `Text`, and `Src` parameters. Multiple block children display on a single line if there is enough space. To separate children on multiple lines, insert a child with [`Type` `Break`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.diagramconnectioncontentblockschildrentype) between them. To insert empty space between blocks, use `DiagramConnectionContentMargin` and its `Top` or `Bottom` parameter.

Declarative rich content is a simpler option to customize the Shape content, compared to [visual functions](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#visual-function). The advantage of visuals is the full control over the Connection content and layout, including the ability to place complex content blocks side by side.

Rich content is also supported with [Diagram data binding](https://www.telerik.com/blazor-ui/documentation/components/diagram/data-bind).

> caption Using declarative rich content in Diagram Connections

<demo metaUrl="client/diagram/connections/rich-content-3/" height="520"></demo>

## Example

> caption Customize Diagram Connections

<demo metaUrl="client/diagram/connections/customization-2/" height="520"></demo>

## Visual Function

You can draw additional Connection content by using the API of the Diagram's JavaScript rendering engine. This is an advanced scenario that is recommended if the desired result cannot be achieved in another way.

The visual function allows a Connection to render:

* Multiple pieces of data with different styles and positions. Without a visual function, each Connection can display one text label.
* Multiple ovals, polygons, and lines. Without a visual function, each Connection is one straight line or a polyline.

To use a visual function:

1. Get familiar with the [related JavaScript API and available visual primitives](https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/ui/diagram/configuration/shapedefaults.visual).
2. Implement a JavaScript function that returns a [`TelerikBlazor.DiagramCommon.Group` JavaScript object](https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/diagram/group). The `Group` can contain any number of other primitives like `Circle`, `Image`, `Line`, `Rectangle`, `TextBlock`, and others.
3. Set the `Visual` parameter of `<DiagramConnectionDefaultsContent>` or `<DiagramConnectionContent>` tag to the JavaScript function name. This will affect either all Connections or a specific Connection.
4. Position each primitive with the `x` and `y` properties of its JavaScript object. Otherwise the primitive renders at the top-left corner of the `Group`.
5. To align or center primitives automatically, use a [`Layout` primitive](https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/diagram/layout) as a parent container. Make sure to `reflow()` the `Layout` object after adding children.
6. Each new primitive element displays on top of the previous ones.
7. (optional) Retrieve Connection parameter values from the the function argument. It is a JavaScript object.
8. (optional) Set the Connection `DataItem` parameter to a JSON-serializable object. Retrieve the object property values from the `dataItem` property of the function argument.

> This section links to the documentation of Kendo UI for jQuery. The Telerik Diagram for Blazor is not a wrapper of the Kendo UI Diagram. However, both components use the same client-side rendering engine. When the Kendo UI documentation mentions the `kendo.dataviz.diagram` JavaScript namespace, you must use `TelerikBlazor.DiagramCommon` instead.

> caption Using Diagram Connection visual function

<demo metaUrl="client/diagram/connections/visual-function-1/" height="550"></demo>

## See Also

* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
* [Diagram API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdiagram)
