diff --git a/components/diagram/connections.md b/components/diagram/connections.md new file mode 100644 index 0000000000..470964fc3b --- /dev/null +++ b/components/diagram/connections.md @@ -0,0 +1,365 @@ +--- +title: Connections +page_title: Diagram - Connections +description: Learn about +slug: diagram-connections +tags: telerik,blazor,diagram +published: True +position: 30 +--- + +# Blazor Diagram Connections + +The connections in the Telerik Diagram for Blazor signify the relationship between two shapes (graph nodes). This article describes all Diagram connection customization options. + +## Basics + +A connection is a link that shows a relationship between two Diagram shapes. A connection can also span across points with specific coordinates, with no associated shapes. + +The fundamental settings of the Telerik Diagram connections (``) include: + +* The `FromId` and `ToId` parameters must match the associated [shape `Id`s](slug:diagram-shapes#basics). You can also define a connection that does not link shapes. In this case, use the `X` and `Y` parameters of the child tags `` and ``. +* The [connection `Type`](#connection-types) determines the connection route and route angles. +* The connection [cap `Type`](#cap-types) determines whether the connections appear directed or undirected. +* The `Selectable` parameter of `` sets if connections can be selected, which determines the ability to [drag or remove](#editability) them. +* `Text` defines the connection label. Use the child `` tag to set it. + +>caption Using Basic Connection Parameters + +````RAZOR.skip-repl + + + +```` + +>caption Using Connections without Shapes + +````RAZOR.skip-repl + + + + +```` + +## Connection Types + +The available Diagram connection types include: + +* `Cascading` (default)—connections display as rectangular routes with one or more right angles. The cascading connection type is suitable for [tree Diagram layouts](slug:diagram-layouts#tree-layout), as the connections enhance the representation of a hierarchy. +* `Polyline`—connections display as polylines that connect the related shapes and all intermediate points. If [connection points](#connection-points) are not defined, then the connection displays as a straight line. + +>caption Setting Connection Type Globally + +````RAZOR.skip-repl + + + +```` + +>caption Setting Type per Connection + +````RAZOR.skip-repl + + + + + +```` + +### Connection Points + +[`Polyline` connections](#connection-types) can pass through multiple points at specific coordinates, no matter if the connections link shapes or not. + +>caption Using Connection Points + +````RAZOR + + + + + + + + + + + + + + +```` + +## Cap Types + +The link between two Diagram shapes is always defined through the `FromId` and `ToId` parameters of the `` tag. From this point of view, a Diagram connection is always directed. However, you can configure the connections to appear bi-directional or non-directional. + +The available cap types are the members of the `DiagramConnectionsStartCapType` and `DiagramConnectionsEndCapType` enums: + +* `ArrowEnd`—the cap arrow points away from the connection, towards the shape +* `FilledCircle` (default) +* `None` + +The configure cap types globally for all connections, use the `Type` parameter of `` and ``. To configure the cap types of a specific connection, use the `Type` parameter of `` and ``. + +Note the difference between caps and selection handles: + +* The caps are visible when a connection is not selected. +* The selection handles are visible when a connection is selected (clicked). + +>caption Setting global and connection-specific cap types + +````RAZOR.skip-repl + + + + + + + + + + + + + +```` + +## Editability + +By default, the Diagram allows users to: + +* Drag a connection by its start and end cap to link other shapes than the current ones. +* Remove the selected connection(s). + +To restrict these operations globally for all connections, use the parameters of the `` tag. + +To restrict operations for a specific connection, use the parameters of the `` tag. + +Connection dragging and removing requires the `Selectable` parameter of `` to be set to `true`, which is by default. + +>caption Setting global and connection-specific editing options + +````RAZOR.skip-repl + + + + + + + + + + + +```` + +## Styling + +The following connection styling options are available in child tags of `` and ``: + +* Text color and font properties, when using connection content +* Background color (fill) for the connection caps +* Background color (fill) for the default and hover states of the selection handles +* Border (stroke) color, type, and width for the caps and selection handles + +>caption Setting global and connection-specific color styles + +````RAZOR.skip-repl + + + + + + + + + + + + + + + + + + + + + + + + + + + +```` + +## Example + +>caption Customize Diagram Connections + +````RAZOR + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +```` + +## 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) +* [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..84c010c9e8 --- /dev/null +++ b/components/diagram/events.md @@ -0,0 +1,118 @@ +--- +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 connection coordinates (if set). + +>caption Using the Diagram OnConnectionClick event + +````RAZOR.skip-repl + + +@code { + private void OnDiagramConnectionClick(DiagramConnectionClickEventArgs args) + { + + } +} +```` + +Also 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`. + +>caption Using the Diagram OnShapeClick event + +````RAZOR.skip-repl + + +@code { + private void OnDiagramShapeClick(DiagramShapeClickEventArgs args) + { + + } +} +```` + +## 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) + { + 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) + { + 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..254cfb3595 --- /dev/null +++ b/components/diagram/layouts.md @@ -0,0 +1,365 @@ +--- +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. 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 display the teams or employess in an organization. + +>caption Using 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 (subgraphs)](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 Using 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`—the root shape is at the top and all descendants are arranged below it +* `Left`—the root shape is on the right +* `Right`—the root shape is on the left +* `Up`—the root shape is at the bottom + +>caption Setting a Layered Diagram Layout Subtype + +````RAZOR.skip-repl + + + +```` + +## Force Layout + +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 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. + +> The force-directed Diagram layout is non-deterministic. Each layout pass is unique, unpredictable, and not reproducible. + +>caption Using the Force Diagram Layout + +````RAZOR.skip-repl + + + +```` + +The force-directed layout type has no subtypes. + +## Example + +The following example demonstrates all Diagram layout types and sub types. + +>caption Using Diagram layouts + +````RAZOR +
+ Layout Type: + + @foreach (DiagramLayoutType layoutType in AllDiagramLayoutTypes) + { + + @layoutType + + } + +
+ +@if (DiagramLayoutType != DiagramLayoutType.Force) +{ +
+ Sub Type: + + @foreach (KeyValuePair kvPair in AllDiagramLayoutSubtypes) + { + + @kvPair.Key + + } + +
+} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@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; + } + } + + private readonly List AllDiagramLayoutTypes = new() + { + DiagramLayoutType.Force, + DiagramLayoutType.Layered, + DiagramLayoutType.Tree + }; + + private readonly Dictionary AllDiagramLayoutSubtypes = new() + { + // The boolean flags denote a Tree-specific layout subtype + { 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 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: + +* 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) +* [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..ca6a73f7f1 --- /dev/null +++ b/components/diagram/overview.md @@ -0,0 +1,288 @@ +--- +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 [Blazor Diagram component](https://www.telerik.com/blazor-ui/diagram) displays relationships between objects or concepts, for example, hierachy. The Diagram provides a variety of built-in shapes and horizontal and vertical layouts. The connections between the graph nodes can be one-directional, bi-directional, or non-directional. The component allows customizing the size, position, and geometric form of its elements. + +## Diagram Elements + +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)) betweem 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). + +## Creating Blazor Diagram + +There are two ways to define and display a Diagram: + +* [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: + +1. Add the `TelerikDiagram` tag. +1. [Define the Diagram layout](slug:diagram-layouts) through the `Type` parameter of the child `` tag. +1. [Define shapes](slug:diagram-shapes) with `` tags inside ``. +1. [Define the connections](slug:diagram-connections) between the shapes with `` tags inside ``. +1. (optional) Define the Diagram `Height`, `Width`, and [initial `Zoom`](#zoom) for optimal display. The default height is `"600px"`. +1. (optional) Define the default type of all Diagram [shapes](slug:diagram-shapes#shape-types) and [connections](slug:diagram-connections#connection-types). + +>caption Basic Blazor Diagram + +````RAZOR + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +```` + +### Define Shapes and Connections in 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"" + } + } + ] + }"; +} +```` + +## Layouts + +The [Diagram provides multiple built-in horizontal and vertical layouts](slug:diagram-layouts), which arrange all shapes and connections automatically, according to specific rules and priorities. Some of the layouts have variations called sub types. + +## Shapes + +The shapes are the graph nodes and the main building blocks of the Diagram component. Learn about the [shape types and available configuration options](slug:diagram-shapes). + +## Connections + +Connections link shapes or points in the Diagram. Users can create, modify or remove connections at runtime. See the [Diagram connection features and settings](slug:diagram-connections). + +## 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. + +>caption Zoom-related Diagram parameters + +````RAZOR.skip-repl + +```` + +## Events + +The Telerik Diagram fires events that enable the app to detect and react to user interactions with the component. Find out more about the [Diagram events and event arguments](slug:diagram-events). + +## Diagram API + +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. + +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 + +* [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) +* [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..b49886bfee --- /dev/null +++ b/components/diagram/shapes.md @@ -0,0 +1,277 @@ +--- +title: Shapes +page_title: Diagram - Shapes +description: Learn about +slug: diagram-shapes +tags: telerik,blazor,diagram +published: True +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 all Diagram shape customization options. + +## 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 + +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 layout though the `` tag. + +>caption Customize Diagram Shapes + +````RAZOR + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@code { + private readonly string Base64SvgImage = "data:image/svg;base64,iVBORw0KGgoAAAANSUhEUgAAAKQAAACkCAMAAAAua3VzAAACylBMVEVMaXFc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBc5QBeULtoAAAA7XRSTlMAgAIEmOsx8uAhAQUG+vX0/AP7/jMdovfO5weHChPmt+/2LkdrrfkWC5/cYDZ5F8vuOA743v0QgXqTHKzjFMjNUG6h8909EejtIBoeiC/J0w+0XL1bPOHMQAySGyXPUvHwVbwmOt9thmwZJ0vl7Fpe0NHKq9mbhWYJMhhBIg10K9Wc5L+L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"; +} +```` + +## 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. + +> 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 shape visual function + +````RAZOR + + + + + + + + + + + + + + + + + + + +@* Move JavaScript code to an external JS file *@ + +```` + +## 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 - + +