Skip to content

Commit bfffc50

Browse files
svdimitrmarin-bratanov
svdimitr
and
marin-bratanov
committed
Update the Charts documentation to better showcase nested tag settings (#62)
* docs(chart): New templates for nested tag settings and updated chart series with the template * chore(docs): updated Columns article to use sequential data for the labels * chore(chart): minor improvements on customization guidance Co-authored-by: Marin Bratanov <[email protected]>
1 parent 2f34915 commit bfffc50

File tree

11 files changed

+354
-17
lines changed

11 files changed

+354
-17
lines changed

‎_contentTemplates/chart/link-to-basics.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,3 +129,58 @@ You can render the lines between the points with different styles. The supported
129129
You can control how transparent the series fill is through the `Opacity` property. `0` means a completely transparent series, and `1` means a completely opaque (non-transparent) fill. You can use decimal values to set the desired transparency (for example, `Opacity="0.3"`).
130130
#end
131131

132+
133+
#tip-look-for-nested-tags
134+
>tip To customize the chart, look for nested tags and heir properties - the inner tags will contain their parent tag name and add specifics to its end. For example, the `ChartSeries` tag has a `ChartSeriesLabels` tag that exposes configuration otions and more child tags.
135+
#end
136+
137+
138+
#configurable-nested-chart-settings
139+
### Customize Chart Elements - Nested Tags Settings
140+
141+
When configuring nested properties and child elements in your chart, the inner tags will contain their parent tag name and add specifics to its end. In general the structure of such nested tags will be `<Chart*Category**Specifics*>` where the Category can be one of the following:
142+
* SeriesItems
143+
* CategoryAxes
144+
* Title
145+
* Legend
146+
* ChartXAxes
147+
* ChartYAxes
148+
* and others
149+
150+
@[template](/_contentTemplates/chart/link-to-basics.md#tip-look-for-nested-tags)
151+
152+
#end
153+
154+
#configurable-nested-chart-settings-categorical
155+
156+
An example of this is the rotation the Labels of a [categorical]({%slug components/chart/databind%}#series-types) chart. You can use the
157+
158+
`ChartCategoryAxes` > `ChartCategoryAxis` > `ChartCategoryAxisLabels` > `ChartCategoryAxisLabelsRotation` tag
159+
160+
and set the `Angle` property to the desired value in degrees (they might be negative or positive numbers). By using similar approach you can take control over `ChartCategoryAxisLabelsMargin` (add margin for top, bottom, left and right), `ChartCategoryAxisLabelsPadding` (add padding for top, bottom, left and right) and others.
161+
162+
This approach is not limited only to the Labels - it can be used with all tags that are applicable for the chart type, for example the Chart Title `ChartTitle` > `ChartTitleMargin`.
163+
164+
#end
165+
166+
#configurable-nested-chart-settings-numerical
167+
168+
For example, for [numerical]({%slug components/chart/databind%}#series-types) charts you can rotate the Labels for `ChartXAxes` or `ChartYAxes` depending on your application design needs and layout. This can be done through the
169+
170+
`ChartXAxes` > `ChartXAxis` > `ChartXAxisLabelsRotation` tag
171+
172+
where you can set the `Angle` property to the desired value in degrees (they might be negative or positive numbers). By using similar approach you can take control over `ChartXAxisLabelsBorder` (add borders), `ChartXAxisLabelsMargin` (add margin for top, bottom, left and right) and others.
173+
174+
This approach is not limited only to the Labels - it can be used with to all tags that are applicable for the chart type, for example the Chart Title `ChartTitle` > `ChartTitleMargin`.
175+
176+
#end
177+
178+
#configurable-nested-chart-settings-axis-free
179+
180+
For example, for [axis-free]({%slug components/chart/databind%}#series-types) charts you can rotate their Labels, Title, Legend and others. Example for doing so is customizing the Chart Series Labels by using the parameters in the
181+
182+
`ChartSeriesItems` > `ChartSeries` > `ChartSeriesLabels` tag and its child tags.
183+
184+
This approach is not limited only to the Labels - it can be used with to all tags that are applicable for the chart type, for example the Chart Title `ChartTitle` > `ChartTitleMargin`.
185+
186+
#end

‎components/chart/overview.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ Basic chart and common settings/elements
5959
};
6060
6161
public List<object> simpleData = new List<object>() { 10, 2, 7, 5 };
62-
62+
6363
public string[] xAxisItems = new string[] { "Q1", "Q2", "Q3", "Q4" };
6464
}
6565
````
@@ -68,9 +68,10 @@ Basic chart and common settings/elements
6868
6969
![](images/overview-chart.png)
7070

71-
>tip When configuring nested properties and child elements in your chart, the inner tags will contain their parent tag name and add specifics to its end. You can see an example of this with the `ChartSeries` > `ChartSeriesLabels` tags in the above example.
7271

7372

73+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)
74+
7475
>caption Component namespace and reference
7576
7677
````CSHTML

‎components/chart/types/area.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,42 @@ You can render the lines between the points with different styles. The supported
9191
9292
![](images/area-chart-step-and-smooth.png)
9393

94+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)
95+
96+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings-categorical)
97+
98+
>caption Change the rendering Step, Color and Font of the Category Axis Labels
99+
100+
````CSHTML
101+
@* Change the rendering Step, Color and Font of the Category Axis Labels *@
102+
103+
<TelerikChart>
104+
<ChartSeriesItems>
105+
<ChartSeries Type="ChartSeriesType.Area" Name="Product 1" Data="@series1Data">
106+
</ChartSeries>
107+
<ChartSeries Type="ChartSeriesType.Area" Name="Product 2" Data="@series2Data">
108+
</ChartSeries>
109+
</ChartSeriesItems>
110+
111+
<ChartCategoryAxes>
112+
<ChartCategoryAxis Categories="@xAxisItems">
113+
<ChartCategoryAxisLabels Step="2" Color="#008000" Font="bold 12px 'Helvetica'"></ChartCategoryAxisLabels>
114+
</ChartCategoryAxis>
115+
</ChartCategoryAxes>
116+
117+
<ChartTitle Text="Quarterly revenue per product"></ChartTitle>
118+
119+
<ChartLegend Position="Telerik.Blazor.ChartLegendPosition.Right">
120+
</ChartLegend>
121+
</TelerikChart>
122+
123+
@code {
124+
public List<object> series1Data = new List<object>() { 10, 2, 7, 5 };
125+
public List<object> series2Data = new List<object>() { 5, 12, 8, 2 };
126+
public string[] xAxisItems = new string[] { "Q1", "Q2", "Q3", "Q4" };
127+
}
128+
````
129+
94130

95131
## See Also
96132

‎components/chart/types/bar.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,60 @@ The color of a series is controlled through the `Color` property that can take a
6868

6969
@[template](/_contentTemplates/chart/link-to-basics.md#gap-and-spacing)
7070

71+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)
72+
73+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings-categorical)
74+
75+
>caption Configuring Label Template for the Value Axis and change the Font of the Category Axis.
76+
77+
````CSHTML
78+
@* Add configuration settings for the Category and Value Axes *@
79+
80+
<TelerikChart>
81+
<ChartTitle Text="Site Visitors Stats"></ChartTitle>
82+
<ChartLegend Visible="false"></ChartLegend>
83+
84+
<ChartSeriesItems>
85+
<ChartSeries Type="ChartSeriesType.Bar" Name="Total Visits" Data="@Series1Data">
86+
</ChartSeries>
87+
<ChartSeries Type="ChartSeriesType.Bar" Name="Unique visitors" Data="@Series2Data">
88+
</ChartSeries>
89+
</ChartSeriesItems>
90+
91+
<ChartValueAxes>
92+
<ChartValueAxis Max="140000">
93+
<ChartValueAxisLabels Template="#=value/1000#k"></ChartValueAxisLabels>
94+
</ChartValueAxis>
95+
</ChartValueAxes>
96+
97+
<ChartCategoryAxes>
98+
<ChartCategoryAxis Categories="@Categories">
99+
<ChartCategoryAxisLabels Font="bold 14px 'Times New Roman'" />
100+
</ChartCategoryAxis>
101+
</ChartCategoryAxes>
102+
103+
</TelerikChart>
104+
105+
@code {
106+
public class ModelData
107+
{
108+
public int Value { get; set; }
109+
}
110+
111+
public List<ModelData>
112+
Data = new List<ModelData>()
113+
{
114+
new ModelData() { Value = 1 },
115+
new ModelData() { Value = 3 },
116+
new ModelData() { Value = 2 },
117+
};
118+
119+
public List<object> Series1Data = new List<object>() { 56000, 63000, 74000, 91000, 117000, 138000 };
120+
public List<object> Series2Data = new List<object>() { 52000, 34000, 23000, 48000, 67000, 83000 };
121+
public string[] Categories = new string[] { "Jan", "Feb", "Mar", "Apr", "May", "Jun" };
122+
}
123+
````
124+
71125
## See Also
72126

73127
* [Live Demo: Bar Chart](https://demos.telerik.com/blazor-ui/chart/index)

‎components/chart/types/bubble.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ position: 0
1010

1111
# Bubble Chart
1212

13-
A **Bubble** chart shows the data as points with coordinates and size defined by their items' values. You might think of a Bubble chart as a variation of the [Scatter chart]({%slug components/chart/types/scatter%}), in which the data points are replaced with bubbles. This allows a Bubble chart to display three dimensional data — two values for the items' coordinates and one for their size.
13+
A **Bubble** chart shows the data as points with coordinates and size defined by their items' values. You might think of a Bubble chart as a variation of the [Scatter chart]({%slug components/chart/types/scatter%}), in which the data points are replaced with bubbles. This allows a Bubble chart to display three dimensional data — two values for the items' coordinates and one for their size.
1414

1515
A Bubble chart is useful for visualizing different scientific relationships (e.g, economical, social, etc.). This chart type's x-axis is also numerical and does not require items.
1616

@@ -100,7 +100,7 @@ To create a bubble chart:
100100

101101
### Color
102102

103-
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 control the fill color of the bubble.
103+
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 control the fill color of the bubble.
104104

105105
The `ColorField` can change the color of individual items. To use it, pass a valid CSS color to the corresponding field in the model and the chart will use its values instead of the `Color` parameter.
106106

@@ -156,6 +156,11 @@ The size field should, generally, have positive values as it correlates to the p
156156
![](images/bubble-chart-negative-values.png)
157157

158158

159+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)
160+
161+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings-numerical)
162+
163+
159164
## See Also
160165

161166
* [Live Demo: Bubble Chart](https://demos.telerik.com/blazor-ui/chart/bubble-chart)

‎components/chart/types/column.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,17 @@ Column series
5959

6060
## Column Chart Specific Appearance Settings
6161

62+
### Markers
63+
64+
Each data item is denoted with a marker (label). You can control and customize them through the `< ChartCategoryAxisLabels />` and its children tags.
65+
66+
* `Visible` - hide all markers by setting this parameter to `false`.
67+
* `Step` - renders every n-th marker, where n is the value(double number) passed to the parameter.
68+
* `Skip` - skips the first n markers, where n is the value(double number) passed to the parameter.
69+
* `Angle` - rotates the markers with the desired angle by n degrees, where n is the value passed to the parameter. It can take positive and negative numbers. To set this parameter use the `< ChartCategoryAxisLabelsRotation />` child tag.
70+
71+
To rotate the markers use the `ChartCategoryAxisLabelsRotation` child tag and set its `Angle` parameter. It can take positive and negative numbers as value.
72+
6273
### Color
6374

6475
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 control the fill color of the area.
@@ -67,6 +78,56 @@ The color of a series is controlled through the `Color` property that can take a
6778

6879
@[template](/_contentTemplates/chart/link-to-basics.md#gap-and-spacing)
6980

81+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings)
82+
83+
@[template](/_contentTemplates/chart/link-to-basics.md#configurable-nested-chart-settings-categorical)
84+
85+
>caption Configuring Label Rotation, Skipping the rendering of every second label and adding borders and padding to the Labels.
86+
87+
````CSHTML
88+
@* Skip rendering every second label and customize them to have borders, padding and rotation. *@
89+
90+
<TelerikChart>
91+
<ChartSeriesItems>
92+
<ChartSeries Type="ChartSeriesType.Column" Name="Product 1" Data="@series1Data">
93+
</ChartSeries>
94+
<ChartSeries Type="ChartSeriesType.Column" Name="Product 2" Data="@series2Data">
95+
</ChartSeries>
96+
</ChartSeriesItems>
97+
98+
<ChartCategoryAxes>
99+
<ChartCategoryAxis Categories="@xAxisItems">
100+
<ChartCategoryAxisLabels Step="2"> @* With this you set the rendering step, in this case it will skip the rendering of every second label *@
101+
<ChartCategoryAxisLabelsRotation Angle="-45"></ChartCategoryAxisLabelsRotation>
102+
<ChartCategoryAxisLabelsPadding Top="10" Left="10" Right="10" Bottom="10"></ChartCategoryAxisLabelsPadding>
103+
<ChartCategoryAxisLabelsBorder Width="1" Color="#FF0000" DashType="DashType.DashDot"></ChartCategoryAxisLabelsBorder>
104+
</ChartCategoryAxisLabels>
105+
</ChartCategoryAxis>
106+
</ChartCategoryAxes>
107+
108+
<ChartTitle Text="Quarterly revenue per product"></ChartTitle>
109+
110+
<ChartLegend Position="ChartLegendPosition.Right">
111+
</ChartLegend>
112+
</TelerikChart>
113+
114+
@code {
115+
public List<object> series1Data = new List<object>() { 10, 2, 5, 6, 8, 8, 13, 11, 4, 9, 10, 15, 14, 3, 2 };
116+
public List<object> series2Data = new List<object>() { 5, 8, 2, 7, 6, 11, 14, 13, 8, 7, 2, 7, 5, 9, 11 };
117+
public string[] xAxisItems = new string[15];
118+
119+
protected override void OnInitialized()
120+
{
121+
for (int i = 0; i < 15; i++)
122+
{
123+
xAxisItems[i] = $"looooong label {i + 1}";
124+
}
125+
base.OnInitialized();
126+
}
127+
}
128+
````
129+
130+
70131
## See Also
71132

72133
* [Live Demo: Column Chart](https://demos.telerik.com/blazor-ui/chart/column-chart)

0 commit comments

Comments
 (0)