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/23] 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/23] 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/23] 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/23] 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+Lvo+UoxJkRerplq81SbgwnigsRCrUtXe6WDkfYkNIkHa5V+KkQq5McISoRomy2zuxtk4kIwhUmYM/f2OmaFM0FWeqmsNhqYots9dWwsdlb9bBX2lKjU94u1l9xYywcntRanPEKZ11N5XgtWiRAAAG0klEQVR42u3d5VcbSxQA8NuEGiEJIRDc3d2KuzsUKnhxitTd3d3d3d2eu7u7y/4P7zxe2xcoyWw2d5LhHO73WX4nszs7c+fuAIAaoTtCZLKQHaHAbljlu3J94ZpvxShRsi6LexpOrWEMEsXulVy/qHQXM0YUhcZxz0RcqIgl4+EWOTdIyFsmM0M08yjiNIRfioQJomnNVU5LXK0xNb7RcqkFpzUslloamRgVvYwjRvysScY0lgcrOT7R22U04pQyc45nmJdNMQpxkoo3sY+pMnyfL3zkxOkYdS0+BiU6lNtwAsKm3MFwg3dGCScwSjLMDGNcvEnOCQ75psUGIHp72HJ6ha2HN+3nJTmJ0zuSkhfSnNZaxnEoEWdJbd4RFGvNIYX1xHFUiJkpfhxixC+Kwh92ahI55ChMRu5zyfccfrjGXcf9IR+ullFgdsbOQ15qbaag5Hpbcbtc8fMSCkrz93fjMtdeyKLAHD0deU2Zs4LGrbnhSiburXn9pJQCc8Y3uMOR+ODHNJifHMVNd0QFbqTxoD+PPInL83WhoMyOQU4YVn3nRYFZdCoBVWk3m8aoyW2rws3KOH47lYLSK9YNt893pbpSYNq2vozL3L2SRp8nvoe7pvT2p3FrSp0DcH/MnQ9oDEchsW24zIDpNPq888e7uFmXmkIKyvDqe8jD0QvjKTDrftiC/KZcbUGB2YS9oNzlTGFCjL80v2xjZKRd43mP8412hLnmhXQjIk3dTPoambgRHrhJEzcaC2kV8yQlKSfO+c6WpBkD6ejfo9aux9+R0OelwYZHzh/41DrPJ7QIGzHDsEi3idaDJO5Icz6rNdaGQ2aeGDz5bHuCsFKWHHU2FLK7MlJD68jKbkLbCd0zDIG09NT2prPwJO2+Bi3Kpo30NiHthMhNSPsIBb5eNJE+gRE8rhERSNiJ87l8UkkLqSi14TensbBJJryCHD/cSwc59xz/3Nloz7mEPs+94oWOFAWt0m3R4rIqiJBrcnsTGWmXovsce3wKaQl6LAkRKXEXdrXECtIk7rMmJKRp+yXBd8+ldsIT1LY6GwM5LrpWjwexNpq0E1cw3UJfpEPrGD1fD+NnE/oc6lea64MUdyxHmA8s7yBU+pn9GiEcuV2FkweXqrYTfsztq0IEIv/AyzSm2xNuTdH6zUpByBbM1VNiOaHPb2cJ6+7fNyFue0Tuy9C+Y5Uu8MERPdyGmbgzua0FOXaM4CFIUY9ZGdD51V0aSIDij+oQmb0vUkEC7HzNGpG53JIKEqDia8QMniw1hwoSzEqrEX/Mkb840kACRM2KR2T2dITRQALsWTMST6lMTaCCBHB/Ha9CYGoAJSRInkNLh44cRQsJ0Hbcln0kwJ5Xw9lHgqJjJftIgOJX4tlHAjTau7KPBHjJU8k+Eoo/L2QfCZC7fxn7SIAF98PZRwIcujkEkACn3h0CSJgTeJp9JICVbwj7SIBD+6TsIwE+/WAIICHKvol9JMBc3zT2kaBYX8Y+EsBnth/7SICEWXL2kQBnhgLSZBg5jBxGDiOHkWpxp5F5pGirywrWkaN8ZdwItpGZ+f/mrZhGKt747xNVlpEZNx8vvdhFLvDd8KQFq0iHGLVyBEaRt/oVjjOJDCjpX3vCIDJn5sAdW+aQjs3P7uIwhpywdbCvGJhCigJuDNqCJWR7voa8GTvIBH+Nl2AFKT7WoHnThhHkZJW28lsmkEEXtRcMMICUrCOlyYyP3PobcTfJ2Mj2+zwKbo2AnKbW7EEnnxZGQN5Ta9acxiZSpX56mChnhyt7SNfYtQMWWxkNrCHLBqnHM/MvYglZ5D/4pwph0U6sIJ2iNR9Oe/iMlAWkfOZYrTPyqgZzbKSutWrmDVWk1ZfpkWlKXGTWZF2QymlH+HwfP89+GSoySZf6ST97vqdahaYiImXJOiBTC/hn0ST1B7CQSntT3sgD9bodbTSn+RoKMjtQzLem91rzHJ0T4uNWhOuPXLPFlGfhscvFPCFpe9GWc3oig28p+JZwbx4ldHdB7F6tB/L0umK+xfDVeh0rbubhJBBpbq/xEKWBSCcPfQ+1WfDFaCHIG29rvmR/ZNpb3vqfAyaq8JTpiIwM/lLbFdWRMs8KnKPKFF3BUl2QTSna/+7/SGlwlwKwwuenDbyRWcdzCVd7iozYPwEww0pVywuZ9s584rUeI2tVeYAdU9IDycjCUh5jSR8yfBuVc7mD2khIpxhe3Td2DBfZ0w0Giv7Iupl3+DXbGSn/03D/ukId6eV8lm+z3Ed/ARgDufegHbAZT5Eui3IB2EZKlxYAMI50Xu8AjCMjutYCsI20zs8DxuPv3l0G+Tv/AJiXQD+0DbN3AAAAAElFTkSuQmCC";
+}
````
-## 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)
From c976317570e31c4afa9283d60d6efd21aafe94e9 Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Thu, 31 Jul 2025 14:37:24 +0300
Subject: [PATCH 21/23] Example and content polishing
---
components/diagram/connections.md | 13 ++-
components/diagram/overview.md | 10 ++-
components/diagram/shapes.md | 130 +++++++++++++++++-------------
3 files changed, 92 insertions(+), 61 deletions(-)
diff --git a/components/diagram/connections.md b/components/diagram/connections.md
index 0dc546af8a..2956d13901 100644
--- a/components/diagram/connections.md
+++ b/components/diagram/connections.md
@@ -41,6 +41,8 @@ The fundamental settings of the Telerik Diagram Connections (`
````
+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](#visual-function).
+
## Connection Types
The available Diagram Connection types include:
@@ -313,15 +315,20 @@ The following Connection styling options are available in child tags of `` or `` tag to the JavaScript function name. The first approach affects all Connections, while the second one affects a specific Connection.
+1. Set the `Visual` parameter of `` or `` tag to the JavaScript function name. This will affect either all Connections or a specific Connection.
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 Connection from the the function argument. It is a JavaScript object.
-1. (optional) Set the Connection `DataItem` parameter to a JSON-serializable object. Retrieve the object properties from the `dataItem` property of the function argument.
+1. (optional) Retrieve Connection parameter values from the the function argument. It is a JavaScript object.
+1. (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.
diff --git a/components/diagram/overview.md b/components/diagram/overview.md
index 61f8f79b69..53b7838b01 100644
--- a/components/diagram/overview.md
+++ b/components/diagram/overview.md
@@ -214,7 +214,7 @@ Connections link shapes or points in the Diagram. Users can create, modify or re
## Zoom
-The Diagram allows users to zoom the graph in and out for better perception. The following code snippet shows the relevant parameters together with their default values. The default `Zoom` value is is effectively `100%` and the maximum zoom is `200%`. A `Zoom` value below `0.5.` may not be readable, unless the shapes use a large font size or users zoom their browser.
+The Diagram allows users to zoom the graph in and out for better perception. The following code snippet shows the relevant parameters together with their default values. The default `Zoom` value is effectively `100%` and the default maximum zoom is `200%`. A `Zoom` value below `0.5` may not be readable, unless the shapes use a large font size or users zoom their browser.
>caption Zoom-related Diagram parameters
@@ -251,9 +251,11 @@ As a rule of thumb, the Diagram markup follows these naming conventions:
````
-* The previous rule has two exceptions. The following tags are direct children of the root `` tag:
- * `` (not a child of ``)
- * `` (not a child of ``)
+* The previous rule has the following exceptions:
+ * `` is a child of ``.
+ * `` is a child of ``.
+ * `` is a child of ``.
+ * `` is a child of ``.
## Diagram Reference
diff --git a/components/diagram/shapes.md b/components/diagram/shapes.md
index ab4425f3ec..e0ed4e5d93 100644
--- a/components/diagram/shapes.md
+++ b/components/diagram/shapes.md
@@ -32,7 +32,11 @@ The fundamental settings of the Telerik Diagram Shapes include:
````
-In addition to the above, use the `X` and `Y` Shape parameters to define the exact Shape position coordinates. These parameters have effect only when a [predefined Diagram layout](slug:diagram-layouts) is not set.
+In addition to the above, you can use the following Shape parameters:
+
+* `X` and `Y` to define the exact Shape position coordinates. These parameters have effect only when a [predefined Diagram layout](slug:diagram-layouts) is not set.
+* `DataItem` to provide an object with additional values to be used in a [visual function](#visual-function).
+* `Path` to define a [custom Shape form](#shape-types).
## Shape Types
@@ -377,27 +381,37 @@ The following configuration is not using a prefefined [Diagram layout](slug:diag
## Visual Function
-You can draw Shapes and render their 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.
+You can draw Shapes and display their 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 single Shape to render:
+
+* Multiple pieces of data with different styles and positions. Without a visual function, each Shape can display one image and one text label.
+* Multiple ovals, polygons, and lines. Without a visual function, each Shape can have a predefined form, or [display a custom form through the `Path` parameter](#example).
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). The `Group` can contain any number of other primitives like `Circle`, `Image`, `Line`, `Rectangle`, `TextBlock`, and others.
-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. Set the `Visual` parameter of `` or `` to the JavaScript function name. This will either affect all Shapes or 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.
+1. (optional) Retrieve the Shape parameter values from the the function argument. It is a JavaScript object that contains all Shape settings, including the global ones in ``.
+1. (optional) Set the Shape `DataItem` parameter to a JSON-serializable object. Retrieve the object property values from the `dataItem` property of the function argument.
+
+When using a visual function, the Diagram ignores all Shape parameters in the Razor markup, but you can still consume these settings from the visual function argument. The only exception is the `Text` parameter of `` and ``, which is always rendered if set.
> 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.
+In addition to the following example, also check this [Blazor Diagram demo](https://demos.telerik.com/blazor-ui/diagram/overview), which uses a visual function.
+
>caption Using Diagram Shape visual function
````RAZOR
-
+
+
@@ -417,57 +431,65 @@ 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" };
+ private ShapeModel ShapeDataItem1 { get; set; } = new()
+ {
+ Title = "First Shape",
+ SubTitle = "New Line and Styles"
+ };
+ private ShapeModel ShapeDataItem2 { get; set; } = new()
+ {
+ Title = "Second Shape",
+ SubTitle = "Additional Text"
+ };
public class ShapeModel
{
From 835dd70cb6d3b94fe48efa9b54161d5640985ffc Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Thu, 31 Jul 2025 16:02:39 +0300
Subject: [PATCH 22/23] Improve visual examples
---
components/diagram/connections.md | 16 +++++----
components/diagram/shapes.md | 60 ++++++++++++++++++-------------
2 files changed, 45 insertions(+), 31 deletions(-)
diff --git a/components/diagram/connections.md b/components/diagram/connections.md
index 2956d13901..0a676f5405 100644
--- a/components/diagram/connections.md
+++ b/components/diagram/connections.md
@@ -326,6 +326,7 @@ To use a visual function:
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). The `Group` can contain any number of other primitives like `Circle`, `Image`, `Line`, `Rectangle`, `TextBlock`, and others.
1. Set the `Visual` parameter of `` or `` tag to the JavaScript function name. This will affect either all Connections or a specific Connection.
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. 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.
1. Each new primitive element displays on top of the previous ones.
1. (optional) Retrieve Connection parameter values from the the function argument. It is a JavaScript object.
1. (optional) Set the Connection `DataItem` parameter to a JSON-serializable object. Retrieve the object property values from the `dataItem` property of the function argument.
@@ -363,12 +364,13 @@ To use a visual function:
@* Move JavaScript code to an external JS file *@
diff --git a/components/diagram/shapes.md b/components/diagram/shapes.md
index e0ed4e5d93..94576eb888 100644
--- a/components/diagram/shapes.md
+++ b/components/diagram/shapes.md
@@ -394,6 +394,7 @@ To use a visual function:
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). The `Group` can contain any number of other primitives like `Circle`, `Image`, `Line`, `Rectangle`, `TextBlock`, and others.
1. Set the `Visual` parameter of `` or `` to the JavaScript function name. This will either affect all Shapes or 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. 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.
1. Each new primitive element displays on top of the previous ones.
1. (optional) Retrieve the Shape parameter values from the the function argument. It is a JavaScript object that contains all Shape settings, including the global ones in ``.
1. (optional) Set the Shape `DataItem` parameter to a JSON-serializable object. Retrieve the object property values from the `dataItem` property of the function argument.
@@ -410,7 +411,7 @@ In addition to the following example, also check this [Blazor Diagram demo](http
-
+
@@ -432,50 +433,61 @@ In addition to the following example, also check this [Blazor Diagram demo](http
@* Move JavaScript code to an external JS file *@
@@ -488,7 +500,7 @@ In addition to the following example, also check this [Blazor Diagram demo](http
private ShapeModel ShapeDataItem2 { get; set; } = new()
{
Title = "Second Shape",
- SubTitle = "Additional Text"
+ SubTitle = "Centered Text"
};
public class ShapeModel
From 790abe77280e9e10c4b9d1f530aeda4b2f0f3c38 Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Fri, 1 Aug 2025 16:46:20 +0300
Subject: [PATCH 23/23] Add CornerRadius and RelativePadding
---
components/diagram/shapes.md | 26 +++++++++++++++++++-------
1 file changed, 19 insertions(+), 7 deletions(-)
diff --git a/components/diagram/shapes.md b/components/diagram/shapes.md
index 94576eb888..0a709237ba 100644
--- a/components/diagram/shapes.md
+++ b/components/diagram/shapes.md
@@ -137,6 +137,7 @@ Some Shape types provide unique behavior or settings:
````
* 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.
+* All shapes, except `Circle`, `Image`, `Rectangle`, and `Text` can display with rounded corners. See [`CornerRadius` in the Styling section](#styling).
>caption Using transparent Rectangle shapes instead of Text shapes
@@ -215,12 +216,17 @@ The following Shape styling options are available in child tags of `` and `` have a `CornerRadius` parameter that rounds both the border and the background at the Shape corners. If you need a rectangle shape with rounded corners, then use the [`Process` Shape type](#shape-types) instead of `Rectangle`.
+* `` and `` have a `RelativePadding` parameter that adds padding as a ratio of the Shape width. For example, `RelativePadding="0.1"` applies a 10% padding. In some cases, you can increase the padding to force the Shape text to wrap.
+
>caption Setting global and Shape-specific color styles
````RAZOR.skip-repl
-
-
+
+
@@ -228,8 +234,8 @@ The following Shape styling options are available in child tags of `
-
-
+
+
@@ -324,13 +330,19 @@ The following configuration is not using a prefefined [Diagram layout](slug:diag
-
-
+