Skip to content

Commit 04b3e2c

Browse files
ntachevadimodi
andauthored
Sankey docs (#2090)
* docs(sankey): add initial docs * chore(sankey): add events samples * chore(sankey): add labels, links and nodes * Update components/sankeydiagram/customization/labels.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankeydiagram/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankeydiagram/customization/labels.md Co-authored-by: Dimo Dimov <[email protected]> * chore(sankey): refactor structure and add legend * chore(sankey): update legend article * chore(sankey): add tooltip and title articles * chore(sankey): add data binding * chore(sankey): add data binding example * chore(sankey): updates * chore(sankey): add title position type * chore(sankey): add see also sections * Update components/sankey/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/links.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/links.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/links.md Co-authored-by: Dimo Dimov <[email protected]> * docs(sankey): add default value in parameter tables * Update components/sankey/elements/nodes.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/labels.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/legend.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/links.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/legend.md * chore(sankey): address feedback --------- Co-authored-by: Dimo Dimov <[email protected]>
1 parent 1e06a1e commit 04b3e2c

File tree

10 files changed

+1459
-0
lines changed

10 files changed

+1459
-0
lines changed

_config.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,9 @@ navigation:
168168
"*components/chart/tooltip":
169169
title: "Tooltips"
170170
position: 31
171+
"*components/sankey/elements":
172+
title: "Elements"
173+
position: 5
171174
"*components/stockchart/types":
172175
title: "Types"
173176
position: 12
@@ -433,6 +436,8 @@ navigation:
433436
title: "RadioGroup"
434437
"*rootcomponent":
435438
title: "RootComponent"
439+
"*sankey":
440+
title: "Sankey"
436441
"*scheduler":
437442
title: "Scheduler"
438443
"*scrollview":

components/sankey/data-bind.md

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
title: Data Binding
3+
page_title: Sankey Diagram Data Binding
4+
description: Data Binding of the Sankey Diagram for Blazor.
5+
slug: sankey-data-binding
6+
tags: telerik,blazor,sankey,diagram,chart,data,binding
7+
published: True
8+
position: 3
9+
---
10+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
11+
12+
13+
# Sankey Data Binding
14+
15+
This article describes the data binding mechanism in the Sankey diagram for Blazor and the supported data source type.
16+
17+
## Data Type and Structure
18+
19+
The Sankey diagram for Blazor requires its `Data` parameter to provide all the data for its nodes, links and labels. The `Data` parameter accepts an object of type [`SankeyData`](/blazor-ui/api/Telerik.Blazor.Components.SankeyData) that contains the following properties:
20+
21+
| Property | Type | Description |
22+
| --------- | ---- | ----------- |
23+
| `Links` | `SankeyDataLinks` | A [`List<SankeyDataLink>` that describes the links](#link). |
24+
| `Nodes` | `SankeyDataNodes ` | A [`List<SankeyDataNode>` that describes the nodes and their labels](#node). |
25+
26+
### Link
27+
28+
The `SankeyDataLink` object contains all the information for the link. It exposes the following properties:
29+
30+
| Property | Type and Default&nbsp;Value | Description |
31+
| --------- | ---- | ----------- |
32+
| `ColorType` | `SankeyLinksColorType` enum <br/> (`SankeyLinksColorType.Static`) | The color type of the link. Provides the following values <ul><li>`Static` the link color is set based on the `Color` property;</li><li>`Source` - the link color is set based on the source node color; </li><li>`Target` - the link color is set based on the target node color; </li></ul> |
33+
| `Color` | `string` | The color of the link. Applies when `ColorType="@SankeyLinksColorType.Static"`. |
34+
| `Highlight` | [`SankeyDataLinkHighlight`](/blazor-ui/api/Telerik.Blazor.Components.SankeyDataLinkHighlight) | The opacity of the active and inactive links when the user hovers a link. |
35+
| `Opacity` | `double?` | The opacity of the link. |
36+
| `SourceId` | `object` | The source node ID of the link. The source node is the node from which the link originates. Required. |
37+
| `TargetId` | `object` | The target node ID of the link. The target node is the node to which the link points. Required. |
38+
| `Value` | `double?` | The value of the link. The value represents the weight of the link and determines the width of the link. Required. |
39+
40+
>tip The visual properties (`Color`, `Opacity` etc.) are not required. You can use these properties to [provide custom settings for the separate links through the data](#customize-elements-through-data). If you want to apply the same settings for all the links in the Sankey use the [component options]({%slug sankey-links%}).
41+
42+
### Node
43+
44+
The `SankeyDataNode` object contains all the information for the node and its label. It exposes the following properties:
45+
46+
| Property | Type and Default&nbsp;Value | Description |
47+
| --------- | ---- | ----------- |
48+
| `Color` | `string` | The color of the node. Accepts a valid CSS color string, including hex and rgb. |
49+
| `Id` | `object` | The ID of the node. The ID is used to connect the nodes with the links. Required. |
50+
| `Label` | [`SankeyDataNodeLabel`](/blazor-ui/api/Telerik.Blazor.Components.SankeyDataNodeLabel) | Contains all the information for the node label - text, alignment, color, border and more. |
51+
| `Offset` | [`SankeyDataNodeOffset`](/blazor-ui/api/Telerik.Blazor.Components.SankeyDataNodeOffset)| The left and top offset of the node from the `<div class="k-sankey">` container. |
52+
| `Opacity` | `double?` | The opacity of the node. |
53+
| `Padding` | `double?` | The minimum vertical space between two nodes. |
54+
| `Width` | `double?` | The width of the node. |
55+
| `Align` | `SankeyNodesAlign?` enum <br/> (`SankeyNodesAlign.Stretch`) | The alignment of the node. Supports the following values - `Stretch`, `Left`, and `Right`.|
56+
57+
>tip The visual properties (`Color`, `Opacity` etc.) are not required. You can use these properties to [provide custom settings for the separate nodes through the data](#customize-elements-through-data). If you want to apply the same settings for all the nodes and labels in the Sankey use the component options for [nodes]({%slug sankey-nodes%}) and [labels]({%slug sankey-labels%}).
58+
59+
## Customize Elements Through Data
60+
61+
The example below showcases binding the Sankey data and adding some specific options for the separate nodes, links and labels.
62+
63+
````CSHTML
64+
<TelerikSankey Data="@Data"
65+
Width="1000px"
66+
Height="400px">
67+
<SankeyLinks ColorType="@SankeyLinksColorType.Source"/>
68+
<SankeyLabels>
69+
<SankeyLabelsStroke Color="none"/>
70+
</SankeyLabels>
71+
</TelerikSankey>
72+
73+
@code {
74+
private SankeyData Data { get; set; }
75+
76+
protected override void OnInitialized()
77+
{
78+
Data = new SankeyData()
79+
{
80+
Nodes = new SankeyDataNodes()
81+
{
82+
new SankeyDataNode()
83+
{
84+
Id = 1,
85+
Color = "#CC8DD6",
86+
Label = new SankeyDataNodeLabel() { Text = "Tablet (12%)", Font="bold 14px sans-serif" }
87+
},
88+
new SankeyDataNode()
89+
{
90+
Id = 2,
91+
Color = "#2D73F5",
92+
Label = new SankeyDataNodeLabel() { Text = "Mobile (40%)", Font="bold 14px sans-serif" }
93+
},
94+
new SankeyDataNode()
95+
{
96+
Id = 3,
97+
Color = "#28B4C8",
98+
Label = new SankeyDataNodeLabel() { Text = "Desktop (48%)", Font="bold 14px sans-serif" }
99+
},
100+
new SankeyDataNode()
101+
{
102+
Id = 4,
103+
Color = "#78D237",
104+
Label = new SankeyDataNodeLabel() { Text = "< 18 years (8%)" }
105+
},
106+
new SankeyDataNode()
107+
{
108+
Id = 5,
109+
Color = "#FFD246",
110+
Label = new SankeyDataNodeLabel() { Text = "18-26 years (35%)" }
111+
},
112+
new SankeyDataNode()
113+
{
114+
Id = 6,
115+
Color = "#FF6358",
116+
Label = new SankeyDataNodeLabel() { Text = "27-40 years (38%)" }
117+
},
118+
new SankeyDataNode()
119+
{
120+
Id = 7,
121+
Color = "#E7607B",
122+
Label = new SankeyDataNodeLabel() { Text = "> 40 years (19%)" }
123+
},
124+
},
125+
126+
Links = new SankeyDataLinks()
127+
{
128+
new SankeyDataLink() { SourceId = 1, TargetId = 4, Value = 4, Opacity = 0.3},
129+
new SankeyDataLink() { SourceId = 1, TargetId = 7, Value = 8, Opacity = 0.5 },
130+
new SankeyDataLink() { SourceId = 2, TargetId = 4, Value = 4, Opacity = 0.3 },
131+
new SankeyDataLink() { SourceId = 2, TargetId = 5, Value = 24, Opacity = 0.8 },
132+
new SankeyDataLink() { SourceId = 2, TargetId = 6, Value = 10, Opacity = 0.6 },
133+
new SankeyDataLink() { SourceId = 2, TargetId = 7, Value = 2, Opacity = 0.2 },
134+
new SankeyDataLink() { SourceId = 3, TargetId = 5, Value = 11, Opacity = 0.6 },
135+
new SankeyDataLink() { SourceId = 3, TargetId = 6, Value = 28, Opacity = 0.8 },
136+
new SankeyDataLink() { SourceId = 3, TargetId = 7, Value = 9, Opacity = 0.5 }
137+
}
138+
};
139+
}
140+
}
141+
````
142+
143+
## Next Steps
144+
145+
* [Add a Title to the Sankey Diagram]({%slug sankey-title%})
146+
* [Configure the Sankey Legend]({%slug sankey-legend%})
147+
* [Explore the Sankey Events]({%slug sankey-events%})
148+
149+
## See Also
150+
151+
* [Live Demo: Sankey Diagram](https://demos.telerik.com/blazor-ui/sankey/overview)
152+
* [Sankey Links]({%slug sankey-links%})
153+
* [Sankey Nodes]({%slug sankey-nodes%})
154+
* [Sankey Labels]({%slug sankey-labels%})

components/sankey/elements/labels.md

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: Labels
3+
page_title: Sankey Labels
4+
description: Node labels in the Sankey Diagram for Blazor.
5+
slug: sankey-labels
6+
tags: telerik,blazor,sankey,diagram,chart,labels
7+
published: True
8+
position: 5
9+
---
10+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
11+
12+
# Sankey Labels
13+
14+
The Sankey diagram Labels represent the [node]({%slug sankey-nodes%}) names. The labels can show over the nodes or next to them. This article explains how to customize the labels in the UI for Blazor Sankey diagram. Each setting applies to all labels in the Sankey diagram.
15+
16+
>tip Each setting applies to all labels in the Sankey diagram. If you want to provide different settings for the separate labels, [customize them through the data source]({%slug sankey-data-binding%}#customize-elements-through-data).
17+
18+
## Basic Customization
19+
20+
To customize the labels, declare a `<SankeyLabels>` tag as a direct child of `<TelerikSankey>`. The `<SankeyLabels>` tag has the following parameters:
21+
22+
| Parameter | Type and Default&nbsp;Value | Description |
23+
| --------- | ---- | ----------- |
24+
| `Align` | `string` | The alignment of the labels. |
25+
| `Color` | `string` | The color of the labels. |
26+
| `Font` | `string` | The font of the labels. |
27+
| `Position` | `string` <br/> (`inside`) | The position of the labels. The supported values are: <ul><li>`inside` - the label is positioned after the node, except for the nodes at the end of the Sankey, that are placed before the node;</li><li>`before` - the label is positioned before the node; </li><li>`after` - the label is positioned after the node; </li></ul> |
28+
| `Visible` | `bool` <br/> (`true`) | Whether the labels are visible. |
29+
30+
31+
## Nested Customization Tags
32+
33+
The `<SankeyLabels>` tag exposes child tags for customization of the labels' border, margin, offset, padding and stroke.
34+
35+
### Border
36+
37+
By design, the labels do not have border. You may add border by declaring the `<SankeyLabelsBorder>` tag inside the `<SankeyLabels>` and specifying the desired settings. The `<SankeyLabelsBorder>` provides the following parameters:
38+
39+
| Parameter | Type and Default&nbsp;Value | Description |
40+
| --------- | ---- | ----------- |
41+
| `Color` | `string` | The color of the border. |
42+
| `DashType` | `DashType` enum <br/> (`DashType.Solid`) | The type of the border. |
43+
| `Width` | `double?` | The width of the border. |
44+
45+
### Margin
46+
47+
The `<SankeyLabelsMargin>` child tag provides the following properties:
48+
49+
| Parameter | Type | Description |
50+
| --------- | ---- | ----------- |
51+
| `Left` | `double?` | The left margin of the labels. |
52+
| `Right` | `double?` | The right margin of the labels. |
53+
54+
### Offset
55+
56+
The `<SankeyLabelsOffset>` child tag provides the following properties:
57+
58+
| Parameter | Type | Description |
59+
| --------- | ---- | ----------- |
60+
| `Left` | `double?` | The left offset of the labels. |
61+
| `Top` | `double?` | The top offset of the labels. |
62+
63+
### Padding
64+
65+
The `<SankeyLabelsPadding>` child tag provides the following properties:
66+
67+
| Parameter | Type | Description |
68+
| --------- | ---- | ----------- |
69+
| `Top` | `double?` | The top padding of the labels. |
70+
| `Bottom` | `double?` | The bottom padding of the labels. |
71+
| `Left` | `double?` | The left padding of the labels. |
72+
| `Right` | `double?` | The right padding of the labels. |
73+
74+
### Stroke
75+
76+
The `<SankeyLabelsStroke>` child tag provides the following properties:
77+
78+
| Parameter | Type | Description |
79+
| --------- | ---- | ----------- |
80+
| `Color` | `string` | The color of the stroke. |
81+
| `LineJoin` | `string` | The [line join](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linejoin) of the stroke. |
82+
| `Left` | `double?` | The width of the stroke. |
83+
84+
## Example
85+
86+
Here is an example customization of the labels in the Sankey diagram.
87+
88+
````CSHTML
89+
<TelerikSankey Data="@Data"
90+
Width="700px"
91+
Height="400px">
92+
<SankeyLabels Font="Monaco">
93+
<SankeyLabelsBorder Color="black" DashType="@DashType.LongDash" Width="1"></SankeyLabelsBorder>
94+
<SankeyLabelsPadding Top="5" Bottom="5" Left="10" Right="10"></SankeyLabelsPadding>
95+
<SankeyLabelsStroke Color="none"></SankeyLabelsStroke>
96+
</SankeyLabels>
97+
</TelerikSankey>
98+
99+
@code {
100+
private SankeyData Data { get; set; }
101+
private string EventLog { get; set; } = string.Empty;
102+
103+
#region Data generation
104+
105+
protected override void OnInitialized()
106+
{
107+
Data = new SankeyData()
108+
{
109+
Nodes = new SankeyDataNodes(),
110+
Links = new SankeyDataLinks()
111+
};
112+
113+
Data.Nodes.Add(new SankeyDataNode() { Id = 1, Label = new SankeyDataNodeLabel() { Text = "Tablet (12%)" } });
114+
Data.Nodes.Add(new SankeyDataNode() { Id = 2, Label = new SankeyDataNodeLabel() { Text = "Mobile (40%)" } });
115+
Data.Nodes.Add(new SankeyDataNode() { Id = 3, Label = new SankeyDataNodeLabel() { Text = "Desktop (48%)" } });
116+
Data.Nodes.Add(new SankeyDataNode() { Id = 4, Label = new SankeyDataNodeLabel() { Text = "< 18 years (8%)" } });
117+
Data.Nodes.Add(new SankeyDataNode() { Id = 5, Label = new SankeyDataNodeLabel() { Text = "18-26 years (35%)" } });
118+
Data.Nodes.Add(new SankeyDataNode() { Id = 6, Label = new SankeyDataNodeLabel() { Text = "27-40 years (38%)" } });
119+
Data.Nodes.Add(new SankeyDataNode() { Id = 7, Label = new SankeyDataNodeLabel() { Text = "> 40 years (19%)" } });
120+
121+
122+
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 4, Value = 4 });
123+
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 7, Value = 8 });
124+
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 4, Value = 4 });
125+
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 5, Value = 24 });
126+
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 6, Value = 10 });
127+
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 7, Value = 2 });
128+
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 5, Value = 11 });
129+
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 6, Value = 28 });
130+
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 7, Value = 9 });
131+
}
132+
133+
#endregion Data generation
134+
}
135+
````
136+
137+
## See Also
138+
139+
* [Live Demo: Sankey Diagram Configuration](https://demos.telerik.com/blazor-ui/sankey/configuration)
140+
* [Sankey Links]({%slug sankey-links%})
141+
* [Sankey Nodes]({%slug sankey-nodes%})
142+
* [Sankey Legend]({%slug sankey-legend%})
143+
* [Sankey Title]({%slug sankey-title%})
144+
* [Sankey Tooltip]({%slug sankey-tooltip%})

0 commit comments

Comments
 (0)