From 9d4eb20bf883c03438f2387e71dd7b36128fba24 Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Thu, 26 Jun 2025 09:29:54 +0300
Subject: [PATCH 01/20] docs(Diagram): Add Diagram documentation
---
components/diagram/connections.md | 16 ++
components/diagram/events.md | 81 +++++++++++
components/diagram/layouts.md | 151 +++++++++++++++++++
components/diagram/overview.md | 234 ++++++++++++++++++++++++++++++
components/diagram/shapes.md | 16 ++
docs-builder.yml | 2 +
introduction.md | 3 +-
7 files changed, 502 insertions(+), 1 deletion(-)
create mode 100644 components/diagram/connections.md
create mode 100644 components/diagram/events.md
create mode 100644 components/diagram/layouts.md
create mode 100644 components/diagram/overview.md
create mode 100644 components/diagram/shapes.md
diff --git a/components/diagram/connections.md b/components/diagram/connections.md
new file mode 100644
index 0000000000..52669c2cde
--- /dev/null
+++ b/components/diagram/connections.md
@@ -0,0 +1,16 @@
+---
+title: Connections
+page_title: Diagram - Connections
+description: Learn about
+slug: diagram-connections
+tags: telerik,blazor,diagram
+published: True
+position: 30
+---
+
+# Blazor Diagram Connections
+
+## See Also
+
+* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
+* [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram)
diff --git a/components/diagram/events.md b/components/diagram/events.md
new file mode 100644
index 0000000000..95f406bc2c
--- /dev/null
+++ b/components/diagram/events.md
@@ -0,0 +1,81 @@
+---
+title: Events
+page_title: Diagram - Events
+description: Learn about the Blazor Diagram component events and experiment with them in the provided runnable code examples.
+slug: diagram-events
+tags: telerik,blazor,diagram
+published: True
+position: 100
+---
+
+# Blazor Diagram Events
+
+The Telerik Blazor Diagram fires events that are related to different user actions. This article describes all these events and their event arguments:
+
+* [`OnConnectionClick`](#onconnectionclick)
+* [`OnShapeClick`](#onshapeclick)
+
+## OnConnectionClick
+
+The `OnConnectionClick` event fires when the user clicks on a connection, including the connection ends that rest on the shape boundaries. The event argument is of type [`DiagramConnectionClickEventArgs`](slug:Telerik.Blazor.Components.DiagramConnectionClickEventArgs) and it provides information about the linked shapes (if they exist) or about the coordinates of the connection ends (if set).
+
+See the [example](#example) below.
+
+## OnShapeClick
+
+The `OnShapeClick` event fires when the user clicks on a shape. The event argument is of type [`DiagramShapeClickEventArgs`](slug:Telerik.Blazor.Components.DiagramShapeClickEventArgs) and provides the shape `Id`.
+
+## Example
+
+The following example demonstrates all Diagram events in action.
+
+>caption Using Diagram events
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+@DiagramEventLog
+
+@code {
+ private string DiagramEventLog { get; set; } = string.Empty;
+
+ private void OnDiagramConnectionClick(DiagramConnectionClickEventArgs args)
+ {
+ DiagramEventLog = $"Clicked on the connection between shapes \"{args.FromId}\" and \"{args.ToId}\".";
+ }
+
+ private void OnDiagramShapeClick(DiagramShapeClickEventArgs args)
+ {
+ DiagramEventLog = $"Clicked on shape \"{args.Id}\".";
+ }
+}
+````
+
+## See Also
+
+* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
+* [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram)
diff --git a/components/diagram/layouts.md b/components/diagram/layouts.md
new file mode 100644
index 0000000000..fa26eee4de
--- /dev/null
+++ b/components/diagram/layouts.md
@@ -0,0 +1,151 @@
+---
+title: Layouts
+page_title: Diagram - Layouts
+description: Learn about the built-in predefined Blazor Diagram layouts and experiment with them in the provided runnable code examples.
+slug: diagram-layouts
+tags: telerik,blazor,diagram
+published: True
+position: 10
+---
+
+# Blazor Diagram Layouts
+
+The Telerik Blazor Diagram provides a few built-in layouts, so that you don't have to define the positions of all shapes and connections manually.
+
+## Force Layout
+
+## Layered
+
+## Tree Layout
+
+## Example
+
+The following example demonstrates all Diagram layout types and sub types.
+
+>caption Using Diagram layouts
+
+````RAZOR
+Layout Type:
+
+ Force
+ Layered
+ Tree
+
+
+@if (DiagramLayoutType != DiagramLayoutType.Force)
+{
+
+ Sub Type:
+
+ Down
+ Left
+ Mind Map H
+ Mind Map V
+ Radial
+ Right
+ Tip Over
+ Up
+
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+@code {
+ private DiagramLayoutType DiagramLayoutType { get; set; } = DiagramLayoutType.Tree;
+
+ private DiagramLayoutSubtype DiagramLayoutSubtype { get; set; } = DiagramLayoutSubtype.Down;
+
+ private void DiagramLayoutTypeChanged(bool newSelected, DiagramLayoutType newDiagramLayoutType)
+ {
+ if (newSelected)
+ {
+ DiagramLayoutType = newDiagramLayoutType;
+ }
+ }
+
+ private void DiagramLayoutSubtypeChanged(bool newSelected, DiagramLayoutSubtype newDiagramLayoutSubtype)
+ {
+ if (newSelected)
+ {
+ DiagramLayoutSubtype = newDiagramLayoutSubtype;
+ }
+ }
+}
+````
+
+## See Also
+
+* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
+* [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram)
diff --git a/components/diagram/overview.md b/components/diagram/overview.md
new file mode 100644
index 0000000000..a8466b6151
--- /dev/null
+++ b/components/diagram/overview.md
@@ -0,0 +1,234 @@
+---
+title: Overview
+page_title: Diagram - Overview
+description: The Blazor DIagram component
+slug: diagram-overview
+tags: telerik,blazor,diagram
+published: True
+position: 0
+---
+
+# Blazor Diagram Overview
+
+The Diagram for Blazor.
+
+
+## Diagram Elements
+
+* A Diagram item is called a *shape*.
+* The relationship (link) betweem two Diagram shapes is called a *connection*.
+
+## Creating Blazor Diagram
+
+There are two ways to define and display a Diagram:
+
+* Define the shapes and connections in the component declaration (easier and discussed in this section).
+* [Define the shapes and connections in a JSON that the Diagram loads at runtime](#create-diagram-from-json) (more flexible and discussed in the section below).
+
+To create the Telerik Diagram for Blazor declaratively:
+
+1. Add the `TelerikDiagram` tag.
+1. Define the Diagram layout through the `Type` parameter of the child `` tag.
+1. Define one or multiple shapes with `` tags inside ``.
+1. Define the connections between the shapes with `` tags inside ``.
+1. (optional) Define the Diagram `Height`, `Width`, and initial `Zoom` for optimal display.
+1. (optional) Define the default type of all Diagram shapes and connections.
+
+>caption Basic Blazor Diagram
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+````
+
+## Create Diagram from JSON
+
+To load the shape and connection data from JSON:
+
+1. [Capture the Diagram component reference through the `@ref` attribute](#diagram-reference).
+1. Execute the Diagram [`LoadFromJsonAsync(string json)` method](slug:Telerik.Blazor.Components.TelerikDiagram#methods).
+
+The minimum required JSON information includes:
+
+* Shape `id`'s as strings.
+* Shape `x` and `y` coordinates as pixel numbers.
+* Connection `from.shapeId` and `to.shapeId` if the connection links shapes. Otherwise, set the start and end coordinates with `from.x`, `from.y`, `to.x`, and `to.y`.
+
+Optionally, you can also define:
+
+* Shape `width` and `height` as numbers.
+* Connection `from.connector` and `to.connector` that determine which shape side the connection touches (`"Top"`, `"Right"`, `"Bottom"`, `"Left"`).
+
+The Diagram provides a `SaveAsJsonAsync()` method that returns the current shape and connection state as a JSON string. This allows you to persist user changes or see how to define more advanced shape and connection settings in JSON format.
+
+>caption Loading and saving the Diagram shape and connection state
+
+````RAZOR
+Make changes and
+Save Diagram to JSON
+
+Make more changes and restore with
+Load Diagram from JSON
+
+
+
+
+
+
+
+
+ @DiagramJson
+
+
+@code {
+ private TelerikDiagram? DiagramRef { get; set; }
+
+ private async Task OnSaveButtonClick()
+ {
+ if (DiagramRef is not null)
+ {
+ DiagramJson = await DiagramRef.SaveAsJsonAsync();
+ }
+ }
+
+ private async Task OnLoadButtonClick()
+ {
+ if (DiagramRef is not null)
+ {
+ await DiagramRef.LoadFromJsonAsync(DiagramJson);
+ }
+ }
+
+ protected override async Task OnAfterRenderAsync(bool firstRender)
+ {
+ if (firstRender && DiagramRef is not null)
+ {
+ await Task.Delay(1); // wait for HTML and client-side Diagram instance
+ await DiagramRef.LoadFromJsonAsync(DiagramJson);
+ StateHasChanged();
+ }
+
+ await base.OnAfterRenderAsync(firstRender);
+ }
+
+ private string DiagramJson { get; set; } = @"
+ {
+ ""shapes"": [
+ {
+ ""id"": ""shape1"",
+ ""content"": {
+ ""text"": ""Shape 1""
+ },
+ ""x"": 200,
+ ""y"": 50
+ },
+ {
+ ""id"": ""shape2"",
+ ""content"": {
+ ""text"": ""Shape 2""
+ },
+ ""height"": 100,
+ ""width"": 160,
+ ""x"": 50,
+ ""y"": 200
+ },
+ {
+ ""id"": ""shape3"",
+ ""content"": {
+ ""text"": ""Shape 3""
+ },
+ ""x"": 300,
+ ""y"": 200
+ }
+ ],
+ ""connections"": [
+ {
+ ""from"": {
+ ""shapeId"": ""shape1""
+ },
+ ""to"": {
+ ""shapeId"": ""shape2""
+ }
+ },
+ {
+ ""from"": {
+ ""shapeId"": ""shape1"",
+ ""connector"":""Right""
+ },
+ ""to"": {
+ ""shapeId"": ""shape3"",
+ ""connector"":""Top""
+ }
+ }
+ ]
+ }";
+}
+````
+
+## Diagram API
+
+Get familiar with all Diagram parameters, methods, events, and nested tags in the [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram).
+
+## Diagram Reference
+
+The [Blazor Diagram component exposes methods](slug:Telerik.Blazor.Components.TelerikDiagram#methods) for programmatic operation. To use them, define a reference to the component instance with the `@ref` directive attribute. Blazor populates component references in `OnAfterRenderAsync`, so they are not available earier.
+
+See a full example in section [Create Diagram from JSON](#create-diagram-from-json) above.
+
+>caption Using the Diagram reference
+
+````RAZOR.skip-repl
+
+
+@code {
+ private TelerikDiagram? DiagramRef { get; set; }
+}
+````
+
+## Next Steps
+
+* [Handle Diagram events](slug:diagram-events)
+
+
+## See Also
+
+* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
+* [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram)
diff --git a/components/diagram/shapes.md b/components/diagram/shapes.md
new file mode 100644
index 0000000000..a444a2cef9
--- /dev/null
+++ b/components/diagram/shapes.md
@@ -0,0 +1,16 @@
+---
+title: Shapes
+page_title: Diagram - Shapes
+description: Learn about
+slug: diagram-shapes
+tags: telerik,blazor,diagram
+published: True
+position: 20
+---
+
+# Blazor Diagram Shapes
+
+## See Also
+
+* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
+* [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram)
diff --git a/docs-builder.yml b/docs-builder.yml
index 3874b46e82..7b9e904b03 100644
--- a/docs-builder.yml
+++ b/docs-builder.yml
@@ -334,6 +334,8 @@ meta:
title: Card
"*calendar":
title: Calendar
+ "*diagram":
+ title: Diagram
tag-helpers/scheduling/multiviewcalendar:
title: MultiViewCalendar
html-helpers/scheduling/multiviewcalendar:
diff --git a/introduction.md b/introduction.md
index b34fc00c05..7b8fbc2bf0 100644
--- a/introduction.md
+++ b/introduction.md
@@ -90,7 +90,8 @@ You can watch a YouTube playlist of getting started tutorials for Telerik UI for
-
+
+
From 6a6d20d0c3e319d7092922e9c943884f2bd905e7 Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Fri, 27 Jun 2025 23:08:10 +0300
Subject: [PATCH 02/20] docs(Diagram): Continued
---
components/diagram/connections.md | 76 +++++++++++++++++
components/diagram/events.md | 15 +++-
components/diagram/shapes.md | 135 ++++++++++++++++++++++++++++++
3 files changed, 224 insertions(+), 2 deletions(-)
diff --git a/components/diagram/connections.md b/components/diagram/connections.md
index 52669c2cde..bddba15da0 100644
--- a/components/diagram/connections.md
+++ b/components/diagram/connections.md
@@ -10,6 +10,82 @@ position: 30
# Blazor Diagram Connections
+## Example
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+````
+
## See Also
* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
diff --git a/components/diagram/events.md b/components/diagram/events.md
index 95f406bc2c..ab830590fb 100644
--- a/components/diagram/events.md
+++ b/components/diagram/events.md
@@ -17,7 +17,7 @@ The Telerik Blazor Diagram fires events that are related to different user actio
## OnConnectionClick
-The `OnConnectionClick` event fires when the user clicks on a connection, including the connection ends that rest on the shape boundaries. The event argument is of type [`DiagramConnectionClickEventArgs`](slug:Telerik.Blazor.Components.DiagramConnectionClickEventArgs) and it provides information about the linked shapes (if they exist) or about the coordinates of the connection ends (if set).
+The `OnConnectionClick` event fires when the user clicks on a connection, including the connection ends that rest on the shape boundaries. The event argument is of type [`DiagramConnectionClickEventArgs`](slug:Telerik.Blazor.Components.DiagramConnectionClickEventArgs) and it provides information about the linked shapes (if they exist) or about the connection coordinates (if set).
See the [example](#example) below.
@@ -55,6 +55,10 @@ The following example demonstrates all Diagram events in action.
+
+
+
+
@@ -65,7 +69,14 @@ The following example demonstrates all Diagram events in action.
private void OnDiagramConnectionClick(DiagramConnectionClickEventArgs args)
{
- DiagramEventLog = $"Clicked on the connection between shapes \"{args.FromId}\" and \"{args.ToId}\".";
+ if (args.FromX != null)
+ {
+ DiagramEventLog = $"Clicked on the connection between coordinates {{{args.FromX}, {args.FromY}}} and {{{args.ToX}, {args.ToY}}}.";
+ }
+ else
+ {
+ DiagramEventLog = $"Clicked on the connection between shapes \"{args.FromId}\" and \"{args.ToId}\".";
+ }
}
private void OnDiagramShapeClick(DiagramShapeClickEventArgs args)
diff --git a/components/diagram/shapes.md b/components/diagram/shapes.md
index a444a2cef9..589b06caeb 100644
--- a/components/diagram/shapes.md
+++ b/components/diagram/shapes.md
@@ -10,6 +10,141 @@ position: 20
# Blazor Diagram Shapes
+
+
+## Example
+
+The following configuration is not using a prefefined [Diagram layout](slug:diagram-layouts). However, you can remove all Shape `X` and `Y` parameters and set a define a layout though the `` tag.
+
+>caption Customize Diagram Shapes
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+````
+
+## Visuals
+
+https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/diagram/group
+
+https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/ui/diagram/configuration/shapedefaults.visual
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+@* Move JavaScript code to an external JS file *@
+
+````
+
## See Also
* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
From 4977fdaf6086f841b609c7b0a1f9cd1cc74ca447 Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Mon, 30 Jun 2025 17:22:00 +0300
Subject: [PATCH 03/20] docs(Diagram): continued
---
components/diagram/events.md | 6 +-
components/diagram/layouts.md | 211 ++++++++++++++++++++++++++++-----
components/diagram/overview.md | 57 ++++++---
3 files changed, 222 insertions(+), 52 deletions(-)
diff --git a/components/diagram/events.md b/components/diagram/events.md
index ab830590fb..291d93aa7e 100644
--- a/components/diagram/events.md
+++ b/components/diagram/events.md
@@ -71,17 +71,17 @@ The following example demonstrates all Diagram events in action.
{
if (args.FromX != null)
{
- DiagramEventLog = $"Clicked on the connection between coordinates {{{args.FromX}, {args.FromY}}} and {{{args.ToX}, {args.ToY}}}.";
+ DiagramEventLog = $"Clicked on the connection between coordinates ({args.FromX}, {args.FromY}) and ({args.ToX}, {args.ToY}).";
}
else
{
- DiagramEventLog = $"Clicked on the connection between shapes \"{args.FromId}\" and \"{args.ToId}\".";
+ DiagramEventLog = $"Clicked on the connection between shapes '{args.FromId}' and '{args.ToId}'.";
}
}
private void OnDiagramShapeClick(DiagramShapeClickEventArgs args)
{
- DiagramEventLog = $"Clicked on shape \"{args.Id}\".";
+ DiagramEventLog = $"Clicked on shape '{args.Id}'.";
}
}
````
diff --git a/components/diagram/layouts.md b/components/diagram/layouts.md
index fa26eee4de..30e03dfc36 100644
--- a/components/diagram/layouts.md
+++ b/components/diagram/layouts.md
@@ -10,13 +10,99 @@ position: 10
# Blazor Diagram Layouts
-The Telerik Blazor Diagram provides a few built-in layouts, so that you don't have to define the positions of all shapes and connections manually.
+The Telerik Blazor Diagram provides a few built-in layouts, so that you don't have to define the positions of all shapes and connections manually. The Diagram supports the most popular layout algorithms, including tree layout, force-directed layout and layered layout.
+
+## Tree Layout
+
+The Tree Diagram layout positions the shapes in a hierarchical way. A typical use case for this layout is to represent the teams or employess in an organization.
+
+>caption Setting the Tree Diagram Layout
+
+````RAZOR.skip-repl
+
+
+
+````
+
+### Tree Layout Subtypes
+
+The Layered Diagram layout has the following sub types:
+
+* `Down`—the root shape is at the top and all descendants are arranged below it
+* `Left`—the root shape is on the right
+* `MindMapHorizontal`—the root shape is at the center and all descendants are arranged to the left and right in a balanced way
+* `MindMapVertical`—the root shape is at the center and all descendants are arranged above and below it in a balanced way
+* `Radial`—the root shape is at the center and all descendants are arranged around it
+* `Right`—the root shape is on the left
+* `TipOver`—a variation of the `Down` sub type. The root shape is at the top. The direct children are arranged horizontally in a row, while the grand children are arranged verticallu on columns.
+* `Up`—the root shape is at the bottom
+
+>caption Setting a Tree Diagram Layout Subtype
+
+````RAZOR.skip-repl
+
+
+
+````
+
+## Layered Layout
+
+The [Layered Diagram layout](https://en.wikipedia.org/wiki/Layered_graph_drawing) positions shapes with an emphasis on the flow. The nodes (shapes) are positioned in horizontal or vertical layers (rows). The layered layout type minimizes the:
+
+* Distance between linked shapes
+* Connection lengths
+* Crossings between layers of shapes.
+
+The layered layout works best with:
+
+* One-direction flows that match the layout subtype
+* No [components (non-linked groups of shapes)](slug:diagram-overview#diagram-elements)
+* No cycles (connections flowing back upstream)
+
+When the graph is a tree, the layout reduces to a standard tree layout and thus can be considered as an extension to the classic tree layout.
+
+>caption Setting the Layered Diagram Layout
+
+````RAZOR.skip-repl
+
+
+
+````
+
+### Layered Layout Subtypes
+
+The Layered Diagram layout has the following sub types. Each subtype name signifies the direction in which descendant nodes are positioned with regard to their ancestor.
+
+* `Down`
+* `Left`
+* `Right`
+* `Up`
+
+>caption Setting a Layered Diagram Layout Subtype
+
+````RAZOR.skip-repl
+
+
+
+````
## Force Layout
-## Layered
+The [Force-directed Diagram layout](https://en.wikipedia.org/wiki/Force-directed_graph_drawing) (also known as the spring-embedder algorithm) is based on a physical simulation of forces acting on the Diagram nodes (shapes), whereby the links (connections) define whether two nodes act upon each other. Each link is like a spring embedded in the Diagram. The simulation attempts to find a minimum energy state, so that the springs are in their base state and do not pull or push any linked node.
-## Tree Layout
+> The force-directed Diagram layout is non-deterministic. Each layout pass is unique, unpredictable, and not reproducible.
+
+>caption Setting the Layered Diagram Layout
+
+````RAZOR.skip-repl
+
+
+
+````
+
+The force-directed layout type has no subtypes.
## Example
@@ -27,12 +113,14 @@ The following example demonstrates all Diagram layout types and sub types.
````RAZOR
Layout Type:
- Force
- Layered
- Tree
+ @foreach (DiagramLayoutType layoutType in AllDiagramLayoutTypes)
+ {
+
+ @layoutType
+
+ }
@if (DiagramLayoutType != DiagramLayoutType.Force)
@@ -40,33 +128,22 @@ Layout Type:
Sub Type:
- Down
- Left
- Mind Map H
- Mind Map V
- Radial
- Right
- Tip Over
- Up
+ @foreach (KeyValuePair kvPair in AllDiagramLayoutSubtypes)
+ {
+
+ @kvPair.Key
+
+ }
}
-
+
-
+
@@ -142,9 +219,81 @@ Layout Type:
DiagramLayoutSubtype = newDiagramLayoutSubtype;
}
}
+
+ private readonly List AllDiagramLayoutTypes = new()
+ {
+ DiagramLayoutType.Force,
+ DiagramLayoutType.Layered,
+ DiagramLayoutType.Tree
+ };
+
+ private readonly Dictionary AllDiagramLayoutSubtypes = new()
+ {
+ // DiagramLayoutSubtype subtype, bool Tree layout only
+ { DiagramLayoutSubtype.Down, false },
+ { DiagramLayoutSubtype.Left, false },
+ { DiagramLayoutSubtype.MindMapHorizontal, true },
+ { DiagramLayoutSubtype.MindMapVertical, true },
+ { DiagramLayoutSubtype.Radial, true },
+ { DiagramLayoutSubtype.Right, false },
+ { DiagramLayoutSubtype.TipOver, true },
+ { DiagramLayoutSubtype.Up, false }
+ };
}
````
+## Layout Grid Settings
+
+A single Diagram instance may display multiple groups of linked shapes that are not connected to one another. Such [separate groups of shapes are called components](slug:diagram-overview#diagram-elements).
+
+The `` tag exposes settings that allow you to define:
+
+* The horizontal and vertical distance (spacing) between the components inside the Diagram.
+* The horizontal and vertical distance (offset) between the components and the Diagram boundaries.
+* The width of the layout grid. If the width is large enough, the Diagram displays multiple components (groups) in a single row. Otherwise the components fall one below another.
+
+>caption Using Diagram Layout Grid settings
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+````
+
## See Also
* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
diff --git a/components/diagram/overview.md b/components/diagram/overview.md
index a8466b6151..05c8eeb253 100644
--- a/components/diagram/overview.md
+++ b/components/diagram/overview.md
@@ -10,20 +10,23 @@ position: 0
# Blazor Diagram Overview
-The Diagram for Blazor.
-
+The [Blazor Diagram component](https://www.telerik.com/blazor-ui/diagram) displays a hierarchy or relationships between objects or concepts. The Diagram provides a variety of built-in horizontal and vertical layouts. The component allows customizing the size, position, and geometric form of its elements.
## Diagram Elements
-* A Diagram item is called a *shape*.
-* The relationship (link) betweem two Diagram shapes is called a *connection*.
+The Diagram component UI consists of the following elements:
+
+* *Shapes* are the main Diagram nodes or building blocks. Shapes can display text and images.
+* *Connections* are the lines or visual links betweem Diagram shapes. Normally, a connection links two Diagram shapes, but a connection can also exist without related shapes.
+* *Connectors* are the 5 dots that appear on the Shape boundaries and center on hover. Users can grab a connector and drag it to another shape to create a new connection.
+* *Component* is a group of connected shapes that are not linked to another collection of connected shapes within the same Diagram.
## Creating Blazor Diagram
There are two ways to define and display a Diagram:
* Define the shapes and connections in the component declaration (easier and discussed in this section).
-* [Define the shapes and connections in a JSON that the Diagram loads at runtime](#create-diagram-from-json) (more flexible and discussed in the section below).
+* [Define the shapes and connections in a JSON](#create-diagram-from-json) (more flexible and discussed in the section below).
To create the Telerik Diagram for Blazor declaratively:
@@ -44,28 +47,22 @@ To create the Telerik Diagram for Blazor declaratively:
-
-
+
-
-
+
-
-
+
-
-
+
-
-
+
-
-
+
@@ -207,6 +204,28 @@ Make more changes and restore with
Get familiar with all Diagram parameters, methods, events, and nested tags in the [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram).
+As a rule of thumb, the Diagram markup follows these naming conventions:
+
+* Tag names in plural wrap tag names in singular:
+ ````RAZOR.skip-repl
+
+
+
+ ````
+* Tags are nested, so that child tag names use their parent tag name with an appended word:
+ ````RAZOR.skip-repl
+
+
+
+
+
+
+
+ ````
+* The previous rule has two exceptions. The following tags are direct children of the root `` tag:
+ * `` (not a child of ``)
+ * `` (not a child of ``)
+
## Diagram Reference
The [Blazor Diagram component exposes methods](slug:Telerik.Blazor.Components.TelerikDiagram#methods) for programmatic operation. To use them, define a reference to the component instance with the `@ref` directive attribute. Blazor populates component references in `OnAfterRenderAsync`, so they are not available earier.
@@ -225,9 +244,11 @@ See a full example in section [Create Diagram from JSON](#create-diagram-from-js
## Next Steps
+* [Define Diagram layouts](slug:diagram-layouts)
+* [Configure Diagram shapes](slug:diagram-shapes)
+* [Customize Diagram connections](slug:diagram-connections)
* [Handle Diagram events](slug:diagram-events)
-
## See Also
* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
From 9bb89253f508e43f4eae04c2e8d4b484820c1deb Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Tue, 1 Jul 2025 17:10:48 +0300
Subject: [PATCH 04/20] docs(Diagram): continued
---
components/diagram/connections.md | 84 ++++++++++++-
components/diagram/layouts.md | 4 +-
components/diagram/overview.md | 21 ++--
components/diagram/shapes.md | 200 ++++++++++++++++++++++++------
4 files changed, 260 insertions(+), 49 deletions(-)
diff --git a/components/diagram/connections.md b/components/diagram/connections.md
index bddba15da0..cfad852b5a 100644
--- a/components/diagram/connections.md
+++ b/components/diagram/connections.md
@@ -12,6 +12,8 @@ position: 30
## Example
+>caption Customize Diagram Connections
+
````RAZOR
@@ -78,7 +80,7 @@ position: 30
-
+
@@ -86,6 +88,86 @@ position: 30
````
+## 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 only if the desired result cannot be achieved in another way.
+
+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).
+1. 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).
+1. Set the `Visual` parameter of `` or `` tag to the JavaScript function name. The first approach affects all connections, while the second one affects a specific connection.
+
+> 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
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+@* Move JavaScript code to an external JS file *@
+
+````
+
## See Also
* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
diff --git a/components/diagram/layouts.md b/components/diagram/layouts.md
index 30e03dfc36..f989d441ab 100644
--- a/components/diagram/layouts.md
+++ b/components/diagram/layouts.md
@@ -229,7 +229,7 @@ Layout Type:
private readonly Dictionary AllDiagramLayoutSubtypes = new()
{
- // DiagramLayoutSubtype subtype, bool Tree layout only
+ // The boolean flags denote a Tree-specific layout subtype
{ DiagramLayoutSubtype.Down, false },
{ DiagramLayoutSubtype.Left, false },
{ DiagramLayoutSubtype.MindMapHorizontal, true },
@@ -244,7 +244,7 @@ Layout Type:
## Layout Grid Settings
-A single Diagram instance may display multiple groups of linked shapes that are not connected to one another. Such [separate groups of shapes are called components](slug:diagram-overview#diagram-elements).
+A single Diagram instance may display multiple subgraphs, which are disconnected groups of linked shapes. Such [separate subgraphs are called components](slug:diagram-overview#diagram-elements).
The `` tag exposes settings that allow you to define:
diff --git a/components/diagram/overview.md b/components/diagram/overview.md
index 05c8eeb253..e1c6a1e340 100644
--- a/components/diagram/overview.md
+++ b/components/diagram/overview.md
@@ -16,17 +16,20 @@ The [Blazor Diagram component](https://www.telerik.com/blazor-ui/diagram) displa
The Diagram component UI consists of the following elements:
-* *Shapes* are the main Diagram nodes or building blocks. Shapes can display text and images.
-* *Connections* are the lines or visual links betweem Diagram shapes. Normally, a connection links two Diagram shapes, but a connection can also exist without related shapes.
+* *Shapes* are the Diagram nodes ([vertices](https://en.wikipedia.org/wiki/Vertex_(graph_theory))). Shapes can display text and images.
* *Connectors* are the 5 dots that appear on the Shape boundaries and center on hover. Users can grab a connector and drag it to another shape to create a new connection.
-* *Component* is a group of connected shapes that are not linked to another collection of connected shapes within the same Diagram.
+* *Connections* are the links ([edges](https://en.wikipedia.org/wiki/Glossary_of_graph_theory#edge)) betweem Diagram shapes. Normally, a connection links two Diagram shapes, but a connection can also exist without related shapes.
+* *Caps* are the connection ends. The connections are directional, so each connection has a start cap and end cap. Note that difference between caps and connectors. Although they can overlap visually, connectors belong to a shape, while caps belong to a connection.
+* [*Components*](https://en.wikipedia.org/wiki/Component_(graph_theory)) are groups (subgraphs) of connected shapes within the same Diagram that are not linked to each other.
## Creating Blazor Diagram
There are two ways to define and display a Diagram:
-* Define the shapes and connections in the component declaration (easier and discussed in this section).
-* [Define the shapes and connections in a JSON](#create-diagram-from-json) (more flexible and discussed in the section below).
+* [Define the shapes and connections in the Diagram component declaration](#define-shapes-and-connections-declaratively).
+* [Define the shapes and connections in a JSON](#define-shapes-and-connections-in-json).
+
+### Define Shapes and Connections Declaratively
To create the Telerik Diagram for Blazor declaratively:
@@ -41,9 +44,9 @@ To create the Telerik Diagram for Blazor declaratively:
````RAZOR
-
-
-
+
+
+
@@ -76,7 +79,7 @@ To create the Telerik Diagram for Blazor declaratively:
````
-## Create Diagram from JSON
+### Define Shapes and Connections in JSON
To load the shape and connection data from JSON:
diff --git a/components/diagram/shapes.md b/components/diagram/shapes.md
index 589b06caeb..f68f54f46e 100644
--- a/components/diagram/shapes.md
+++ b/components/diagram/shapes.md
@@ -10,7 +10,107 @@ position: 20
# Blazor Diagram Shapes
+The shape is the main building block of the Telerik Diagram for Blazor. It represents a single node in the graph. This article describes the shape customization options that the Diagram provides.
+## Basics
+
+The fundamental settings of the Telerik Diagram shapes include:
+
+* The [shape `Type`](#shape-types) determines the overall appearance and content.
+* The shape `Id` is required in order to define connections between related shapes.
+* `Text` defines the shape label. Use the child `` tag to set it.
+* `Width` and `Height` determine the shape size in pixels. The default values are `100`.
+
+>caption Using basic Shape parameters
+
+````RAZOR.skip-repl
+
+
+
+````
+
+In addition to the above, use the `X` and `Y` shape parameters to define the shape position coordinates. These parameters have effect only when a [predefined Diagram layout](slug:diagram-layouts) is not set.
+
+## Shape Types
+
+The available Diagram shape types include:
+
+* `Circle`—you can use different `Width` and `Height` values to define an ellipse.
+* `Image`—all shape types support text labels, but only the `Image` shape can display a graphic. Use the `` `Source` parameter to define the image URL or data URI.
+* `Rectangle` (default)
+* `Text`—unlike the other shape types, the `Text` shape has no borders and background.
+
+>caption Using Image shapes
+
+````RAZOR.skip-repl
+
+
+
+````
+
+## Styling
+
+The following shape styling options are available in child tags of `` and ``:
+
+* Text color and font properties
+* Background color (fill) and opacity for the default and hover states
+* Rotation angle
+* Border (stroke) color, type, width, and opacity
+
+>caption Setting global and shape-specific color styles
+
+````RAZOR.skip-repl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+````
+
+## Editability
+
+By default, the Diagram allows users to:
+
+* Connect one shape to other shapes.
+* Drag a shape to new coordinates.
+* Remove the selected shape(s).
+
+To restrict these operations globally for all shapes, use the parameters of the `` tag.
+
+To restrict or enable operations for a specific shape, use the parameters of the `` tag.
+
+>caption Setting global and shape-specific editing options
+
+````RAZOR.skip-repl
+
+
+
+
+
+
+
+
+
+
+
+````
## Example
@@ -20,73 +120,78 @@ The following configuration is not using a prefefined [Diagram layout](slug:diag
````RAZOR
-
-
+
+
-
+
-
-
-
-
+
+
-
-
-
+
-
-
+
+
-
+
-
+
-
+
+
+
+
@@ -94,30 +199,42 @@ The following configuration is not using a prefefined [Diagram layout](slug:diag
+
+
+@code {
+ private readonly string Base64SvgImage = "data:image/svg;base64,iVBORw0KGgoAAAANSUhEUgAAAKQAAACkCAMAAAAua3VzAAACylBMVEVMaXFc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBeULtoAAAA7XRSTlMAgAIEmOsx8uAhAQUG+vX0/AP7/jMdovfO5weHChPmt+/2LkdrrfkWC5/cYDZ5F8vuOA743v0QgXqTHKzjFMjNUG6h8909EejtIBoeiC/J0w+0XL1bPOHMQAySGyXPUvHwVbwmOt9thmwZJ0vl7Fpe0NHKq9mbhWYJMhhBIg10K9Wc5L+L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";
+}
````
-## Visuals
+## Visual Function
+
+You can draw shapes by using the API of the Diagram's JavaScript rendering engine. This is an advanced scenario that is recommended only if the desired result cannot be achieved in another way.
+
+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).
+1. 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).
+1. Set the `Visual` parameter of `` or `` tag to the JavaScript function name. The first approach affects all shapes, while the second one affects a specific shape.
+1. (optional) Retrieve information about the current shape from the the function argument. It is a JavaScript object that contains all shape settings.
-https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/diagram/group
+> 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.
-https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/ui/diagram/configuration/shapedefaults.visual
+>caption Using Diagram shape visual function
````RAZOR
-
-
-
+
-
+
@@ -129,16 +246,25 @@ https://www.telerik.com/kendo-jquery-ui/documentation/api/javascript/dataviz/ui/
@* Move JavaScript code to an external JS file *@
+
+@code {
+ private readonly ConnectionModel ConnectionDataItem1 = new() { Title = "1 to 2", Color = "green" };
+ private readonly ConnectionModel ConnectionDataItem2 = new() { Title = "1 to 3", Color = "red" };
+
+ public class ConnectionModel
+ {
+ public string Title { get; set; } = string.Empty;
+ public string Color { get; set; } = "black";
+ }
+}
````
## See Also
diff --git a/components/diagram/layouts.md b/components/diagram/layouts.md
index 6f0c547549..387303b0ad 100644
--- a/components/diagram/layouts.md
+++ b/components/diagram/layouts.md
@@ -361,5 +361,5 @@ The `` tag exposes settings that allow you to define:
## See Also
-* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
+* [Live Demo: Diagram Layout and Shape Types](https://demos.telerik.com/blazor-ui/diagram/configuration)
* [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram)
diff --git a/components/diagram/overview.md b/components/diagram/overview.md
index aaca3581d1..61f8f79b69 100644
--- a/components/diagram/overview.md
+++ b/components/diagram/overview.md
@@ -16,12 +16,14 @@ The [Blazor Diagram component](https://www.telerik.com/blazor-ui/diagram) displa
The Diagram component UI consists of the following elements:
-* *Shapes* are the Diagram nodes ([vertices](https://en.wikipedia.org/wiki/Vertex_(graph_theory))). Shapes can display [text and images](slug:diagram-shapes).
-* *Connectors* are the 5 dots that appear on the Shape boundaries and center on hover. Users can grab a connector and drag it to another shape to create a new connection.
-* *Connections* are the links ([edges](https://en.wikipedia.org/wiki/Glossary_of_graph_theory#edge)) between Diagram shapes. Normally, a [connection links two Diagram shapes, but a connection can also exist without related shapes](slug:diagram-connections).
-* *Caps* are the connection ends. The connections are directional, so each connection has a [start cap and end cap](slug:diagram-connections). Note that difference between caps and connectors. Although they can overlap visually, connectors belong to a shape, while caps belong to a connection.
-* *Selection handles* are the additional visual elements that appear at both ends of a connection when it is selected. The handles appear on top of the caps and connectors.
-* [*Components*](https://en.wikipedia.org/wiki/Component_(graph_theory)) are groups (subgraphs) of connected shapes within the same Diagram that are not linked to each other. The Diagram provides [dedicated settings for such scenarios](slug:diagram-layouts#layout-grid-settings).
+* [*Shapes*](slug:diagram-shapes) are the Diagram nodes ([vertices](https://en.wikipedia.org/wiki/Vertex_(graph_theory))). Shapes can display text and images.
+* [*Connectors*](slug:diagram-shapes#connectors) are the 5 dots that appear on the Shape boundaries and center on hover. Users can grab a connector and drag it to another shape to create a new connection.
+* [*Connections*](slug:diagram-connections) are the links ([edges](https://en.wikipedia.org/wiki/Glossary_of_graph_theory#edge)) between Diagram shapes. Normally, a connection links two Diagram shapes, but a connection can also exist without related shapes.
+* [*Caps*](slug:diagram-connections#cap-types) are the connection ends. The connections are directional, so each connection has a start cap and end cap.
+* [*Selection handles*](slug:diagram-connections#selection-handles) are the additional visual elements that appear at both ends of a connection when it is selected. The handles appear on top of the caps and connectors.
+* [*Components*](slug:diagram-layouts#layout-grid-settings) are groups ([subgraphs]((https://en.wikipedia.org/wiki/Component_(graph_theory)))) of connected shapes within the same Diagram that are not linked to each other. The Diagram provides [dedicated settings for such scenarios].
+
+Note that difference between caps, connectors, and selection handles. Although they can overlap visually, connectors belong to a shape, while caps and selection handles belong to a connection.
## Creating Blazor Diagram
@@ -124,18 +126,12 @@ Make more changes and restore with
private async Task OnSaveButtonClick()
{
- if (DiagramRef is not null)
- {
- DiagramJson = await DiagramRef.SaveAsJsonAsync();
- }
+ DiagramJson = await DiagramRef!.SaveAsJsonAsync();
}
private async Task OnLoadButtonClick()
{
- if (DiagramRef is not null)
- {
- await DiagramRef.LoadFromJsonAsync(DiagramJson);
- }
+ await DiagramRef!.LoadFromJsonAsync(DiagramJson);
}
protected override async Task OnAfterRenderAsync(bool firstRender)
diff --git a/components/diagram/shapes.md b/components/diagram/shapes.md
index 0a2e6d3a6d..ab4425f3ec 100644
--- a/components/diagram/shapes.md
+++ b/components/diagram/shapes.md
@@ -42,19 +42,7 @@ Some Shape types are designed for [flowcharts, also known as workflow or process
The Shape `Path` parameter allows you to manually [define a custom Shape form](#example) with [multiple straight or curved lines](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths) that doesn't match any of the predefined Shape types.
-Some Shape type specifics include:
-
-* The `Circle` Shape can look like an ellipse if you set different `Width` and `Height` values. Generally, all Shapes adjust their form and proportions, based on the set dimensions.
-* All Shape types support text labels, but only the `Image` Shape can display a graphic. Use the `` `Source` parameter to set an image URL or a data URI.
- ````RAZOR.skip-repl
-
-
-
- ````
-* The `Terminator` Shape normally requires a `Width` that is larger than the `Height`.
-* The `Text` Shape has no borders and background. It occupies the minimum required amount of space to enclose the label. You can use the `MinWidth` and `MinHeight` parameters to expand a text label.
-
->caption All Diagram Shapes except Image and Text
+>caption All Diagram Shape types except Image and Text
````RAZOR
@@ -132,6 +120,88 @@ Some Shape type specifics include:
}
````
+### Type-Specific Shape Features
+
+Some Shape types provide unique behavior or settings:
+
+* The `Circle` Shape can look like an ellipse if you set different `Width` and `Height` values. Generally, all Shapes adjust their form and proportions, based on the set dimensions.
+* All Shape types support text labels, but only the `Image` Shape can display a graphic. Use the `` `Source` parameter to set an image URL or a data URI.
+ ````RAZOR.skip-repl
+
+
+
+ ````
+* The `Terminator` Shape normally requires a `Width` that is larger than the `Height`.
+* The `Text` Shape has no borders and background. It occupies the minimum required amount of space to enclose the text content. To display text Shapes with some empty space around the content, use transparent Shapes of another type.
+
+>caption Using transparent Rectangle shapes instead of Text shapes
+
+````RAZOR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+````
+
+## Connectors
+
+Connectors are the 5 dots that appear on the Shape boundaries and center on hover. Users can grab a connector and drag it to another shape to create a new connection. If the user grabs the center connector, the Diagram can create a connection from any side of the Shape. If the user grabs a connector on the Shape's boundary, the Diagram will create a connection from that specific side of the Shape.
+
+You can customize connectors globally or per shape. Connectors settings are part of the shape settings. As a result:
+
+* `` must be a child of ``.
+* `` must be a child of ``.
+
+>caption Configure connectors globally and per Shape
+
+````RAZOR.skip-repl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+````
+
## Styling
The following Shape styling options are available in child tags of `` and ``:
@@ -203,6 +273,13 @@ The following configuration is not using a prefefined [Diagram layout](slug:diag
+
+
+
+
+
+
+
+
+
+
+
+
+
+
` or `` tag to the JavaScript function name. The first approach affects all Shapes, while the second one affects a specific Shape.
+1. 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`.
+1. Each new primitive element displays on top of the previous ones.
1. (optional) Retrieve information about the current Shape from the the function argument. It is a JavaScript object that contains all Shape settings.
+1. (optional) Set the Shape `DataItem` parameter to a JSON-serializable object. Retrieve the object properties 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.
@@ -310,14 +397,16 @@ To use a visual function:
-
+
+
+
-
-
+
+
-
-
+
+
@@ -328,32 +417,68 @@ To use a visual function:
@* Move JavaScript code to an external JS file *@
+
+@code {
+ private readonly ShapeModel ShapeDataItem1 = new() { Title = "First Shape", SubTitle = "New Line and Styles" };
+ private readonly ShapeModel ShapeDataItem2 = new() { Title = "Second Shape", SubTitle = "Additional Text" };
+
+ public class ShapeModel
+ {
+ public string Title { get; set; } = string.Empty;
+ public string SubTitle { get; set; } = string.Empty;
+ }
+}
````
## See Also
-* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
+* [Live Demo: Diagram Layout and Shape Types](https://demos.telerik.com/blazor-ui/diagram/configuration)
+* [Live Demo: Using Diagram Visuals](https://demos.telerik.com/blazor-ui/diagram/overview)
* [Diagram API Reference](slug:Telerik.Blazor.Components.TelerikDiagram)