Skip to content

Commit 473887d

Browse files
dimodiyordan-mitev
dimodi
and
yordan-mitev
authored
docs(chart): Add documentation for range series types (#1536)
* docs(rangecharts): Initial commit * docs(chart): Polish and add articles * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/area.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/bar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/column.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md * Update components/chart/types/rangebar.md * Update components/chart/types/rangecolumn.md * Update components/chart/types/rangearea.md * Update components/chart/types/rangearea.md * Update components/chart/types/rangearea.md * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangebar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangebar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangearea.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangebar.md * Update components/chart/types/rangebar.md * Update components/chart/types/rangebar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangebar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md * Update components/chart/types/rangebar.md * Update components/chart/types/rangebar.md * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangebar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangebar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangebar.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/chart/types/rangecolumn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * address tips --------- Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com>
1 parent 2f2a38b commit 473887d

File tree

6 files changed

+568
-2
lines changed

6 files changed

+568
-2
lines changed

‎components/chart/types/area.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ The <a href="https://www.telerik.com/blazor-ui/area-chart" target="_blank">Blazo
1616

1717
An Area chart emphasizes the volume of money, data or any other unit that the given series has encompassed. When backgrounds are semi-transparent, it lets the user clearly see where different sets of data overlap.
1818

19+
The Area Chart is similar to the [Range Area Chart]({%slug components/chart/types/rangearea%}), which allows the area to raise above the horizontal axis.
20+
1921
@[template](/_contentTemplates/chart/link-to-basics.md#understand-basics-and-databinding-first)
2022

2123
#### To create an area chart:

‎components/chart/types/bar.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ The <a href="https://www.telerik.com/blazor-ui/bar-chart" target="_blank">Blazor
1414

1515
![bar chart](images/bar-chart.png)
1616

17+
The Bar Chart is similar to the [Range Bar Chart]({%slug components/chart/types/rangebar%}), which allows the bar to move away from the category axis.
18+
1719
@[template](/_contentTemplates/chart/link-to-basics.md#understand-basics-and-databinding-first)
1820

1921
#### To create a bar chart:

‎components/chart/types/column.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ The <a href="https://www.telerik.com/blazor-ui/column-chart" target="_blank">Bla
1414

1515
![column chart](images/column-chart.png)
1616

17-
@[template](/_contentTemplates/chart/link-to-basics.md#understand-basics-and-databinding-first)
17+
The Column Chart is similar to the [Range Column Chart]({%slug components/chart/types/rangecolumn%}), which allows the column's low end to start above the horizontal axis.
1818

19-
@[template](/_contentTemplates/date-inputs/general.md#format-placeholder)
19+
@[template](/_contentTemplates/chart/link-to-basics.md#understand-basics-and-databinding-first)
2020

2121
#### To create a column chart:
2222

‎components/chart/types/rangearea.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Range Area
3+
page_title: Chart - Range Area
4+
description: Overview of the Range Area Chart for Blazor with a description of the common use cases and the different ways to data bind the chart. The article lists configuration options and provides Range Area Chart examples.
5+
slug: components/chart/types/rangearea
6+
tags: telerik,blazor,chart,rangearea
7+
published: True
8+
position: 0
9+
---
10+
11+
# Range Area Chart
12+
13+
The <a href="https://www.telerik.com/blazor-ui/range-area-chart" target="_blank">Blazor Range Area Chart</a> shows the data as a colored area between two continuous lines that pass through points defined by pairs of `from` and `to` values. The graph between the border lines has a different customizable color for each series. The Range Area Chart is similar to the [Area Chart]({%slug components/chart/types/area%}), which can be regarded as a Range Area Chart with zero `from` values.
14+
15+
You can use the Range Area Chart to emphasize the difference between pairs of continuous value sequences.
16+
17+
By default, the series backgrounds are semi-transparent, which lets the user clearly see where different sets of data overlap.
18+
19+
@[template](/_contentTemplates/chart/link-to-basics.md#understand-basics-and-databinding-first)
20+
21+
## Creating Blazor Range Area Chart
22+
23+
1. Add a `ChartSeries` to the `ChartSeriesItems` collection.
24+
2. Set the series `Type` parameter to `ChartSeriesType.RangeArea`.
25+
3. Provide a data collection to its `Data` property. You can use a [collection of arrays](#binding-range-area-series-to-collection-of-arrays) or a [collection of custom objects](#binding-range-area-series-to-custom-objects).
26+
4. If the Range Area data is a collection of arrays, provide data for the `Categories` parameter of the `ChartCategoryAxis`.
27+
28+
### Binding Range Area Series to Collection of Arrays
29+
30+
In this case, set the `ChartSeries` `Data` parameter to a `List` of arrays or a jagged array (an array of arrays). The inner arrays should have two members - one for the lower `from` value, and one for the higher `to` value.
31+
32+
Set the `Categories` parameter of the `ChartCategoryAxis` to `object[]`. The members of this array will be used as labels for the category axis in their respective order.
33+
34+
>caption Blazor Range Area Chart bound to arrays
35+
36+
````CSHTML
37+
<TelerikChart>
38+
<ChartSeriesItems>
39+
<ChartSeries Name="Sydney"
40+
Data="@SydneyData"
41+
Type="ChartSeriesType.RangeArea">
42+
</ChartSeries>
43+
<ChartSeries Name="Sofia"
44+
Data="@SofiaData"
45+
Type="ChartSeriesType.RangeArea">
46+
</ChartSeries>
47+
</ChartSeriesItems>
48+
49+
<ChartCategoryAxes>
50+
<ChartCategoryAxis Categories="@MonthNames" />
51+
</ChartCategoryAxes>
52+
53+
<ChartTooltip Visible="true"></ChartTooltip>
54+
55+
<ChartTitle Text="Monthly Temperatures"></ChartTitle>
56+
57+
<ChartLegend Position="ChartLegendPosition.Right"></ChartLegend>
58+
</TelerikChart>
59+
60+
@code {
61+
// The RangeArea series Data can be any collection of arrays
62+
63+
private List<double[]> SydneyData { get; set; } = new List<double[]>
64+
{
65+
new double[] { 20, 27 },
66+
new double[] { 19.9, 26.8 },
67+
new double[] { 18.4, 25.7 },
68+
new double[] { 15.3, 23.6 },
69+
new double[] { 12.3, 20.9 },
70+
new double[] { 10, 18.3 },
71+
new double[] { 8.9, 17.9 },
72+
new double[] { 9.7, 19.3 },
73+
new double[] { 12.3, 21.6 },
74+
new double[] { 14.6, 23.2 },
75+
new double[] { 16.6, 24.2 },
76+
new double[] { 18.4, 25.7 }
77+
};
78+
79+
private double[][] SofiaData { get; set; } = new double[][]
80+
{
81+
new double[] { -3.8, 3.6 },
82+
new double[] { -2.3, 6.5 },
83+
new double[] { 1.1, 11.5 },
84+
new double[] { 5.4, 16.7 },
85+
new double[] { 9.9, 21.4 },
86+
new double[] { 13.4, 25.3 },
87+
new double[] { 15.3, 27.9 },
88+
new double[] { 15.3, 28.4 },
89+
new double[] { 11.1, 23.3 },
90+
new double[] { 6.7, 17.6 },
91+
new double[] { 2.2, 10.7 },
92+
new double[] { -2.3, 4.6 }
93+
};
94+
95+
private object[] MonthNames = new string[] {
96+
"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sept", "Oct", "Nov", "Dec"
97+
};
98+
}
99+
````
100+
101+
### Binding Range Area Series to Custom Objects
102+
103+
1. Set the `ChartSeries` `Data` parameter to an `IEnumerable<T>`.
104+
1. Set the `FromField`, `ToField`, and `CategoryField` parameters of the `ChartSeries` to properties of the `T` type.
105+
106+
>caption Blazor Range Area Chart bound to custom objects
107+
108+
````CSHTML
109+
<TelerikChart>
110+
<ChartSeriesItems>
111+
<ChartSeries Name="Test Tube 1"
112+
Data="@Tube1Data"
113+
Type="ChartSeriesType.RangeArea"
114+
FromField="@nameof(AreaDataPoint.LowValue)"
115+
ToField="@nameof(AreaDataPoint.HighValue)"
116+
CategoryField="@nameof(AreaDataPoint.Hour)">
117+
</ChartSeries>
118+
<ChartSeries Name="Test Tube 2"
119+
Data="@Tube2Data"
120+
Type="ChartSeriesType.RangeArea"
121+
FromField="@nameof(AreaDataPoint.LowValue)"
122+
ToField="@nameof(AreaDataPoint.HighValue)"
123+
CategoryField="@nameof(AreaDataPoint.Hour)">
124+
</ChartSeries>
125+
</ChartSeriesItems>
126+
127+
<ChartTooltip Visible="true"></ChartTooltip>
128+
129+
<ChartTitle Text="Laboratory Measurements"></ChartTitle>
130+
131+
<ChartLegend Position="ChartLegendPosition.Right"></ChartLegend>
132+
</TelerikChart>
133+
134+
@code {
135+
private List<AreaDataPoint> Tube1Data { get; set; } = new List<AreaDataPoint>();
136+
137+
private List<AreaDataPoint> Tube2Data { get; set; } = new List<AreaDataPoint>();
138+
139+
protected override void OnInitialized()
140+
{
141+
var rnd = new Random();
142+
var dataPointCount = 10;
143+
144+
for (int i = 1; i <= dataPointCount; i++)
145+
{
146+
Tube1Data.Add(new AreaDataPoint()
147+
{
148+
Hour = i,
149+
LowValue = rnd.Next(5 * i, 10 * i),
150+
HighValue = rnd.Next(15 * i, 20 * i + 5)
151+
});
152+
153+
Tube2Data.Add(new AreaDataPoint()
154+
{
155+
Hour = i,
156+
LowValue = rnd.Next(5 * (dataPointCount + 1 - i), 10 * (dataPointCount + 1 - i)),
157+
HighValue = rnd.Next(15 * (dataPointCount + 1 - i), 20 * (dataPointCount + 1 - i))
158+
});
159+
}
160+
}
161+
162+
public class AreaDataPoint
163+
{
164+
public int Hour { get; set; }
165+
public int LowValue { get; set; }
166+
public int HighValue { get; set; }
167+
}
168+
}
169+
````
170+
171+
172+
## Range Area Chart Specific Appearance Settings
173+
174+
### Color
175+
176+
The color of a series is controlled through the `Color` property that can take any valid CSS color (for example, `#abcdef`, `#f00`, or `blue`). The property controls the fill color of the area.
177+
178+
You can control the color of the line itself separately by using the `Color` property of the nested `TelerikChartSeriesLine` tag.
179+
180+
@[template](/_contentTemplates/chart/link-to-basics.md#opacity-area-bubble)
181+
182+
### Missing Values
183+
184+
If both values in a range pair are missing or `null`, you can have the Chart work around this by setting the `MissingValues` property of the series to the desired behavior. Use a member of the `Telerik.Blazor.ChartSeriesMissingValues` enum:
185+
186+
* `Zero` (default)—The two lines and the area between them will go to the `0` value mark.
187+
* `Interpolate`—The lines and area will go through the interpolated values of the missing data points and connect to the next data points with a value.
188+
* `Gap`—The range area will contain empty space until the next pair of values.
189+
190+
191+
### Line Style
192+
193+
You can render the lines between the points with different styles. The supported styles can be set via the `Style` property of the child `ChartSeriesLine` tag—it takes a member of the `Telerik.Blazor.ChartSeriesLineStyle` enum:
194+
195+
* `Normal` (default)—This style produces a straight line between data points.
196+
* `Step`—The style renders the connection between data points through vertical and horizontal lines. It is suitable for indicating that the value is constant between the changes.
197+
* `Smooth`—This style causes the Area Chart to display a fitted curve through data points. It is suitable when the data requires to be displayed with a curve, or when you wish to connect the points with smooth instead of straight lines.
198+
199+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)
200+
201+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings-categorical)
202+
203+
204+
## See Also
205+
206+
* [Live Demo: Range Area Chart](https://demos.telerik.com/blazor-ui/chart/range-area-chart)

‎components/chart/types/rangebar.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: Range Bar
3+
page_title: Chart - Range Bar
4+
description: Overview of the Range Bar Chart for Blazor with a description of the common use cases and the different ways to data bind the chart. The article lists configuration options and provides Range Bar Chart examples.
5+
slug: components/chart/types/rangebar
6+
tags: telerik,blazor,chart,rangebar
7+
published: True
8+
position: 0
9+
---
10+
11+
# Range Bar Chart
12+
13+
The <a href="https://www.telerik.com/blazor-ui/range-bar-chart" target="_blank">Blazor Range Bar Chart</a> displays data as horizontal bars whose position and length vary according to pairs of `from` and `to` values. You can use a Range Bar Chart to show a comparison between several sets of data (for example, summaries of quantitative or time data). Each series is automatically colored differently for easier reading. The Range Bar Chart is similar to the [Bar Chart]({%slug components/chart/types/bar%}), which can be regarded as a Range Bar Chart with zero `from` values.
14+
15+
@[template](/_contentTemplates/chart/link-to-basics.md#understand-basics-and-databinding-first)
16+
17+
## Creating Blazor Range Bar Chart
18+
19+
1. Add a `ChartSeries` to the `ChartSeriesItems` collection.
20+
2. Set the series `Type` parameter to `ChartSeriesType.RangeBar`.
21+
3. Provide a data collection to the series `Data` parameter. You can use a [collection of arrays](#binding-range-bar-series-to-collection-of-arrays) or a [collection of custom objects](#binding-range-column-series-to-custom-objects).
22+
4. If the Range Bar data is a collection of arrays, provide data for the `Categories` parameter of the `ChartCategoryAxis`.
23+
24+
### Binding Range Bar Series to Collection of Arrays
25+
26+
Set the `ChartSeries` `Data` parameter to a `List` of arrays or a jagged array (an array of arrays). The inner arrays must have two members—a lower one for the `from` value, and a higher one for `to` value.
27+
28+
Set the `Categories` parameter of the `ChartCategoryAxis` to `object[]`. The members of this array will be used as labels for the category axis in their respective order.
29+
30+
>caption Blazor Range Bar Chart bound to arrays
31+
32+
````CSHTML
33+
<TelerikChart>
34+
<ChartTitle Text="Sleep Hours by Age"></ChartTitle>
35+
36+
<ChartSeriesItems>
37+
<ChartSeries Type="ChartSeriesType.RangeBar" Data="@SleepData">
38+
</ChartSeries>
39+
</ChartSeriesItems>
40+
41+
<ChartCategoryAxes>
42+
<ChartCategoryAxis Categories="@Categories"></ChartCategoryAxis>
43+
</ChartCategoryAxes>
44+
45+
<ChartValueAxes>
46+
<ChartValueAxis Min="4"></ChartValueAxis>
47+
</ChartValueAxes>
48+
49+
<ChartTooltip Visible="true">
50+
<Template>
51+
@{
52+
var dataItem = (int[])context.DataItem;
53+
}
54+
<span>@dataItem[0] - @dataItem[1] hours</span>
55+
</Template>
56+
</ChartTooltip>
57+
58+
</TelerikChart>
59+
60+
@code {
61+
private List<int[]> SleepData = new List<int[]>() {
62+
new int[] { 14, 17 },
63+
new int[] { 12, 16 },
64+
new int[] { 11, 14 },
65+
new int[] { 10, 13 },
66+
new int[] { 9, 12 },
67+
new int[] { 8, 10 },
68+
new int[] { 7, 9 },
69+
new int[] { 7, 8 }
70+
};
71+
72+
private string[] Categories = new string[] {
73+
"0–3 m", "4-12 m", "1-2 y", "3-5 y", "6-12 y", "13-18 y", "18-60 y", "60+ y"
74+
};
75+
}
76+
````
77+
78+
### Binding Range Column Series to Custom Objects
79+
80+
1. Set the `ChartSeries` `Data` parameter to an `IEnumerable<T>`.
81+
1. Set the `FromField`, `ToField`, and `CategoryField` parameters of the `ChartSeries` to properties of the `T` type.
82+
83+
>caption Blazor Range Bar Chart bound to custom objects
84+
85+
````CSHTML
86+
<TelerikChart>
87+
<ChartTitle Text="Sleep Hours by Age"></ChartTitle>
88+
89+
<ChartSeriesItems>
90+
<ChartSeries Type="ChartSeriesType.RangeBar"
91+
Data="@SleepData"
92+
FromField="@(nameof(RangeBarModel.LowValue))"
93+
ToField="@(nameof(RangeBarModel.HighValue))"
94+
CategoryField="@(nameof(RangeBarModel.AgeGroup))">
95+
</ChartSeries>
96+
</ChartSeriesItems>
97+
98+
<ChartValueAxes>
99+
<ChartValueAxis Min="4"></ChartValueAxis>
100+
</ChartValueAxes>
101+
102+
<ChartTooltip Visible="true">
103+
<Template>
104+
@{
105+
var dataItem = (RangeBarModel)context.DataItem;
106+
}
107+
<span>@dataItem.LowValue - @dataItem.HighValue hours</span>
108+
</Template>
109+
</ChartTooltip>
110+
111+
</TelerikChart>
112+
113+
@code {
114+
private List<RangeBarModel> SleepData = new List<RangeBarModel>() {
115+
new RangeBarModel { LowValue = 14, HighValue = 17, AgeGroup = "0-3 m" },
116+
new RangeBarModel { LowValue = 12, HighValue = 16, AgeGroup = "4-12 m" },
117+
new RangeBarModel { LowValue = 11, HighValue = 14, AgeGroup = "1-2 y" },
118+
new RangeBarModel { LowValue = 10, HighValue = 13, AgeGroup = "3-5 y" },
119+
new RangeBarModel { LowValue = 9, HighValue = 12, AgeGroup = "6-12 y" },
120+
new RangeBarModel { LowValue = 8, HighValue = 10, AgeGroup = "13-18 y" },
121+
new RangeBarModel { LowValue = 7, HighValue = 9, AgeGroup = "18-60 y" },
122+
new RangeBarModel { LowValue = 7, HighValue = 8, AgeGroup = "60+ y" }
123+
};
124+
125+
public class RangeBarModel
126+
{
127+
public string AgeGroup { get; set; }
128+
public int LowValue { get; set; }
129+
public int HighValue { get; set; }
130+
}
131+
}
132+
````
133+
134+
## Range Bar Chart Specific Appearance Settings
135+
136+
### Color
137+
138+
The color of a series is controlled through the `Color` property that can take any valid CSS color (for example, `#abcdef`, `#f00`, or `blue`). The color controls the fill color of the area.
139+
140+
@[template](/_contentTemplates/chart/link-to-basics.md#color-field-bar-column)
141+
142+
@[template](/_contentTemplates/chart/link-to-basics.md#gap-and-spacing)
143+
144+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)
145+
146+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings-categorical)
147+
148+
149+
## See Also
150+
151+
* [Live Demo: Range Bar Chart](https://demos.telerik.com/blazor-ui/chart/range-bar-chart)

0 commit comments

Comments
 (0)