From 2a7b2328c0d67955bb299e8640e8af21e107f436 Mon Sep 17 00:00:00 2001 From: Vikram Reddy Date: Mon, 14 Aug 2023 00:21:29 +0530 Subject: [PATCH] BarChart docs update --- blazorbootstrap/Models/Charts/ChartData.cs | 4 +- docs/docs/06-data-visualization/bar-chart.md | 519 +++++++++++++++++-- 2 files changed, 471 insertions(+), 52 deletions(-) diff --git a/blazorbootstrap/Models/Charts/ChartData.cs b/blazorbootstrap/Models/Charts/ChartData.cs index 609c9bfb1..52dc9e94e 100644 --- a/blazorbootstrap/Models/Charts/ChartData.cs +++ b/blazorbootstrap/Models/Charts/ChartData.cs @@ -3,8 +3,8 @@ public class ChartData { [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] - public List? Labels { get; set; } + public List? Datasets { get; set; } [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] - public List? Datasets { get; set; } + public List? Labels { get; set; } } \ No newline at end of file diff --git a/docs/docs/06-data-visualization/bar-chart.md b/docs/docs/06-data-visualization/bar-chart.md index 786052527..5c185a6a1 100644 --- a/docs/docs/06-data-visualization/bar-chart.md +++ b/docs/docs/06-data-visualization/bar-chart.md @@ -1,43 +1,39 @@ --- -title: Blazor Bar Chart Components -description: Blazor Bootstrap charts are well-designed chart components on top of Chart.js to visualize data. It contains a rich UI gallery of charts that cater to all charting scenarios. Its high performance helps render large amounts of data quickly. -image: https://i.imgur.com/ATtFiUZ.png +title: Blazor Bar Chart +description: A Blazor Bootstrap bar chart component is used to represent data values as vertical bars. It is sometimes used to show trend data and to compare multiple data sets side by side. +image: https://i.imgur.com/iJjl1Me.png sidebar_label: Bar Chart sidebar_position: 1 --- -# Blazor Charts +A Blazor Bootstrap bar chart component is used to represent data values as vertical bars. +It is sometimes used to show trend data and to compare multiple data sets side by side. -Blazor Bootstrap charts are well-designed chart components on top of Chart.js to visualize data. It contains a rich UI gallery of charts that cater to all charting scenarios. Its high performance helps render large amounts of data quickly. - -## Blazor Bar Chart - -Blazor Chart Component - Blazor Bar Chart -
-See blazor bar chart demo here. +Blazor Chart Component - Blazor Bar Chart ## Parameters -| Name | Type | Default | Required | Description | -|:--|:--|:--|:--|:--| -| Height | int | | | Gets or sets chart height. | -| Width | int | | | Get or sets chart width. | +| Name | Type | Description | Required | Default | Added Version | +|:--|:--|:--|:--|:--|:--| +| Height | int | Gets or sets chart height. | | | 1.0.0 | +| Width | int | Gets or sets chart width. | | | 1.0.0 | ## Methods -| Name | Descritpion | -|:--|:--| -| InitializeAsync(**ChartData** chartData, **IChartOptions** chartOptions) | Initialize Bar Chart. | -| ResizeAsync(**int** width, **int** height) | Resize the chart. | -| UpdateAsync(**ChartData** chartData, **IChartOptions** chartOptions) | Update Bar Chart. | +| Name | Return type | Descritpion | Added Version | +|:--|:--|:--|:--| +| AddDataAsync | `ChartData` | Adds data to bar chart. | 1.10.0 | +| AddDatasetAsync | `ChartData` | Adds dataset to bar chart. | 1.10.0 | +| InitializeAsync | Task | Initialize Bar Chart. | 1.0.0 | +| UpdateAsync | Task | Update Bar Chart. | 1.0.0 | ## ChartData Members -| Property Name | Type | Default | Required | Description | -|:--|:--|:--|:--|:--| -| Labels | `List` | null | ✔️ | Gets or sets the Labels. | -| Datasets | `List` | null | ✔️ | Gets or sets the Datasets. | +| Property Name | Type | Default | Required | Description | Added Version | +|:--|:--|:--|:--|:--|:--| +| Labels | `List` | null | ✔️ | Gets or sets the Labels. | 1.0.0 | +| Datasets | `List` | null | ✔️ | Gets or sets the Datasets. | 1.0.0 | ## BarChartDataset Members @@ -45,32 +41,455 @@ Blazor Bootstrap charts are well-designed chart components on top of Chart.js to **BarChartDataset** implements **IChartDataset**. ::: -| Property Name | Type | Default | Required | Description | -|:--|:--|:--|:--|:--| -| BackgroundColor | `List` | null | | Get or sets the BackgroundColor. | -| BarPercentage | double | 0.8 | | Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. | -| BorderColor | `List` | null | | Get or sets the BorderColor. | -| BorderRadius | int | 0 | | Border radius. | -| BorderWidth | `List` | null | | Get or sets the BorderWidth. | -| CategoryPercentage | double | 0.8 | | Percent (0-1) of the available width each category should be within the sample width. | -| Clip | string | null | | How to clip relative to chartArea. Positive value allows overflow, negative value clips that many pixels inside chartArea. 0 = clip at chartArea. Clipping can also be configured per side: clip: {left: 5, top: false, right: -2, bottom: 0} | -| Data | `List` | null | | Get or sets the Data. | -| Hidden | bool | false | | Configures the visibility state of the dataset. Set it to true, to hide the dataset from the chart. | -| HoverBackgroundColor | `List` | null | ✔️ | Get or sets the HoverBackgroundColor. | -| HoverBorderColor | `List` | null | ✔️ | Get or sets the HoverBorderColor. | -| HoverBorderWidth | `List` | null | ✔️ | Get or sets the HoverBorderWidth. | -| Label | string | null | | The label for the dataset which appears in the legend and tooltips. | -| Type | string | null | ✔️ | Get or sets the chart type. | -| XAxisID | string | null | | The ID of the x axis to plot this dataset on. | -| YAxisID | string | null | | The ID of the y axis to plot this dataset on. | +| Property Name | Type | Default | Required | Description | Added Version | +|:--|:--|:--|:--|:--|:--| +| BackgroundColor | `List` | null | | Get or sets the BackgroundColor. | 1.0.0 | +| BarPercentage | double | 0.8 | | Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. | 1.0.0 | +| BorderColor | `List` | null | | Get or sets the BorderColor. | 1.0.0 | +| BorderRadius | int | 0 | | Border radius. | 1.0.0 | +| BorderWidth | `List` | null | | Get or sets the BorderWidth. | 1.0.0 | +| CategoryPercentage | double | 0.8 | | Percent (0-1) of the available width each category should be within the sample width. | 1.0.0 | +| Clip | string | null | | How to clip relative to chartArea. Positive value allows overflow, negative value clips that many pixels inside chartArea. 0 = clip at chartArea. Clipping can also be configured per side: clip: {left: 5, top: false, right: -2, bottom: 0} | 1.0.0 | +| Data | `List` | null | | Get or sets the Data. | 1.0.0 | +| Hidden | bool | false | | Configures the visibility state of the dataset. Set it to true, to hide the dataset from the chart. | 1.0.0 | +| HoverBackgroundColor | `List` | null | ✔️ | Get or sets the HoverBackgroundColor. | 1.0.0 | +| HoverBorderColor | `List` | null | ✔️ | Get or sets the HoverBorderColor. | 1.0.0 | +| HoverBorderWidth | `List` | null | ✔️ | Get or sets the HoverBorderWidth. | 1.0.0 | +| Label | string | null | | The label for the dataset which appears in the legend and tooltips. | 1.0.0 | +| Type | string | null | ✔️ | Get or sets the chart type. | 1.0.0 | +| XAxisID | string | null | | The ID of the x axis to plot this dataset on. | 1.0.0 | +| YAxisID | string | null | | The ID of the y axis to plot this dataset on. | 1.0.0 | ## BarChartOptions Members -| Property Name | Type | Default | Required | Description | -|:--|:--|:--|:--|:--| -| IndexAxis | string | x | | The base axis of the chart. 'x' for vertical charts and 'y' for horizontal charts. | -| Interaction | Interaction | | | Gets or sets the Interaction. | -| Layout | ChartLayout | | | Gets or sets the ChartLayout. | -| Plugins | Plugins | | | Gets or sets the Plugins. | -| Responsive | bool | false | | Gets or sets the Responsive. | -| Scales | Scales | | | Gets or sets the Scales. | \ No newline at end of file +| Property Name | Type | Default | Required | Description | Added Version | +|:--|:--|:--|:--|:--|:--| +| IndexAxis | string | x | | The base axis of the chart. 'x' for vertical charts and 'y' for horizontal charts. | 1.0.0 | +| Interaction | `Interaction` | | | Gets or sets the Interaction. | 1.0.0 | +| Layout | `ChartLayout` | | | Gets or sets the ChartLayout. | 1.0.0 | +| Plugins | `Plugins` | | | Gets or sets the Plugins. | 1.0.0 | +| Responsive | bool | false | | Gets or sets the Responsive. | 1.0.0 | +| Scales | `Scales` | | | Gets or sets the Scales. | 1.0.0 | + +## Examples + +### How it works + +In the following example, a categorical 12-color palette is used. + +:::tip +For data visualization, you can use the predefined palettes `ColorBuilder.CategoricalTwelveColors` for a 12-color palette and `ColorBuilder.CategoricalSixColors` for a 6-color palette. +These palettes offer a range of distinct and visually appealing colors that can be applied to represent different categories or data elements in your visualizations. +::: + +Blazor Bootstrap: Bar Chart Component - How it works + +```cshtml {} showLineNumbers + + + + + + + +``` + +```cs {} showLineNumbers +@code { + private BarChart barChart = default!; + private BarChartOptions barChartOptions = default!; + private ChartData chartData = default!; + + private int datasetsCount = 0; + private int labelsCount = 0; + private string[] months = { "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" }; + private Random random = new(); + + protected override void OnInitialized() + { + chartData = new ChartData { Labels = GetDefaultDataLabels(6), Datasets = GetDefaultDataSets(3) }; + barChartOptions = new BarChartOptions { Responsive = true, Interaction = new Interaction { Mode = InteractionMode.Index } }; + } + + protected override async Task OnAfterRenderAsync(bool firstRender) + { + if (firstRender) + { + await barChart.InitializeAsync(chartData, barChartOptions); + } + await base.OnAfterRenderAsync(firstRender); + } + + private async Task RandomizeAsync() + { + if (chartData is null || chartData.Datasets is null || !chartData.Datasets.Any()) return; + + var newDatasets = new List(); + + foreach (var dataset in chartData.Datasets) + { + if (dataset is BarChartDataset barChartDataset + && barChartDataset is not null + && barChartDataset.Data is not null) + { + var count = barChartDataset.Data.Count; + + var newData = new List(); + for (var i = 0; i < count; i++) + { + newData.Add(random.Next(200)); + } + + barChartDataset.Data = newData; + newDatasets.Add(barChartDataset); + } + } + + chartData.Datasets = newDatasets; + + await barChart.UpdateAsync(chartData, barChartOptions); + } + + private async Task AddDatasetAsync() + { + if (chartData is null || chartData.Datasets is null) return; + + if (datasetsCount >= 12) + return; + + var chartDataset = GetRandomBarChartDataset(); + chartData = await barChart.AddDatasetAsync(chartData, chartDataset, barChartOptions); + } + + private async Task AddDataAsync() + { + if (chartData is null || chartData.Datasets is null) + return; + + if (labelsCount >= 12) + return; + + var data = new List(); + foreach (var dataset in chartData.Datasets) + { + if (dataset is BarChartDataset barChartDataset) + data.Add(new BarChartDatasetData(barChartDataset.Label, random.Next(200))); + } + + chartData = await barChart.AddDataAsync(chartData, GetNextDataLabel(), data); + } + + private async Task ShowHorizontalBarChartAsync() + { + barChartOptions.IndexAxis = "y"; + await barChart.UpdateAsync(chartData, barChartOptions); + } + + private async Task ShowVerticalBarChartAsync() + { + barChartOptions.IndexAxis = "x"; + await barChart.UpdateAsync(chartData, barChartOptions); + } + + #region Data Preparation + + private List GetDefaultDataSets(int numberOfDatasets) + { + var datasets = new List(); + + for (var index = 0; index < numberOfDatasets; index++) + { + datasets.Add(GetRandomBarChartDataset()); + } + + return datasets; + } + + private BarChartDataset GetRandomBarChartDataset() + { + var c = ColorBuilder.CategoricalTwelveColors[datasetsCount].ToColor(); + + datasetsCount += 1; + + return new BarChartDataset() + { + Label = $"Product {datasetsCount}", + Data = GetRandomData(), + BackgroundColor = new List { c.ToRgbString() }, + BorderColor = new List { c.ToRgbString() }, + BorderWidth = new List { 0 }, + }; + } + + private List GetRandomData() + { + var data = new List(); + for (var index = 0; index < labelsCount; index++) + { + data.Add(random.Next(200)); + } + + return data; + } + + private List GetDefaultDataLabels(int numberOfLabels) + { + var labels = new List(); + for (var index = 0; index < numberOfLabels; index++) + { + labels.Add(GetNextDataLabel()); + } + + return labels; + } + + private string GetNextDataLabel() + { + labelsCount += 1; + return months[labelsCount - 1]; + } + + #endregion Data Preparation +} +``` + +[See the demo here.](https://demos.blazorbootstrap.com/charts/bar-chart#how-it-works) + +### Horizontal bar chart + +Blazor Bootstrap: Bar Chart Component - Horizontal bar chart + +```cshtml {} showLineNumbers + +``` + +```cs {} showLineNumbers +@code { + private BarChart barChart = default!; + private BarChartOptions barChartOptions = default!; + private ChartData chartData = default!; + + protected override void OnInitialized() + { + var labels = new List { "Chrome", "Firefox", "Safari", "Edge" }; + var datasets = new List(); + + var dataset1 = new BarChartDataset() + { + Data = new List { 55000, 15000, 18000, 21000 }, + BackgroundColor = new List { ColorBuilder.CategoricalTwelveColors[0] }, + BorderColor = new List { ColorBuilder.CategoricalTwelveColors[0] }, + BorderWidth = new List { 0 }, + }; + datasets.Add(dataset1); + + chartData = new ChartData { + Labels = labels, + Datasets = datasets }; + + barChartOptions = new BarChartOptions(); + barChartOptions.Responsive = true; + barChartOptions.Interaction = new Interaction { Mode = InteractionMode.Y }; + barChartOptions.IndexAxis = "y"; + + barChartOptions.Scales.X.Title.Text = "Visitors"; + barChartOptions.Scales.X.Title.Display = true; + + barChartOptions.Scales.Y.Title.Text = "Browser"; + barChartOptions.Scales.Y.Title.Display = true; + + barChartOptions.Plugins.Legend.Display = false; + } + + protected override async Task OnAfterRenderAsync(bool firstRender) + { + if (firstRender) + { + await barChart.InitializeAsync(chartData, barChartOptions); + } + await base.OnAfterRenderAsync(firstRender); + } +} +``` + +[See the demo here.](https://demos.blazorbootstrap.com/charts/bar-chart#horizontal-bar-chart) + +### Stacked bar chart + +Blazor Bootstrap: Bar Chart Component - Stacked bar chart + +```cshtml {} showLineNumbers + +``` + +```cs {} showLineNumbers +@code { + private BarChart barChart = default!; + private BarChartOptions barChartOptions = default!; + private ChartData chartData = default!; + + protected override void OnInitialized() + { + var colors = ColorBuilder.CategoricalTwelveColors; + + var labels = new List { "Chrome", "Firefox", "Safari", "Edge" }; + var datasets = new List(); + + var dataset1 = new BarChartDataset() + { + Label = "Windows", + Data = new List { 28000, 8000, 2000, 17000 }, + BackgroundColor = new List { colors[0] }, + BorderColor = new List { colors[0] }, + BorderWidth = new List { 0 }, + }; + datasets.Add(dataset1); + + var dataset2 = new BarChartDataset() + { + Label = "macOS", + Data = new List { 8000, 10000, 14000, 8000 }, + BackgroundColor = new List { colors[1] }, + BorderColor = new List { colors[1] }, + BorderWidth = new List { 0 }, + }; + datasets.Add(dataset2); + + var dataset3 = new BarChartDataset() + { + Label = "Other", + Data = new List { 28000, 10000, 14000, 8000 }, + BackgroundColor = new List { colors[2] }, + BorderColor = new List { colors[2] }, + BorderWidth = new List { 0 }, + }; + datasets.Add(dataset3); + + chartData = new ChartData + { + Labels = labels, + Datasets = datasets + }; + + barChartOptions = new(); + barChartOptions.Responsive = true; + barChartOptions.Interaction = new Interaction { Mode = InteractionMode.Y }; + barChartOptions.IndexAxis = "y"; + + barChartOptions.Scales.X.Title.Text = "Visitors"; + barChartOptions.Scales.X.Title.Display = true; + + barChartOptions.Scales.Y.Title.Text = "Browser"; + barChartOptions.Scales.Y.Title.Display = true; + + barChartOptions.Scales.X.Stacked = true; + barChartOptions.Scales.Y.Stacked = true; + + barChartOptions.Plugins.Title.Text = "Operating system"; + barChartOptions.Plugins.Title.Display = true; + } + + protected override async Task OnAfterRenderAsync(bool firstRender) + { + if (firstRender) + { + await barChart.InitializeAsync(chartData, barChartOptions); + } + await base.OnAfterRenderAsync(firstRender); + } +} +``` + +[See the demo here.](https://demos.blazorbootstrap.com/charts/bar-chart#stacked-bar-chart) + +### Locale + +By default, the chart is using the default locale of the platform on which it is running. +In the following example, you will see the chart in the **German** locale (**de_DE**). + +Blazor Bootstrap: Bar Chart Component - Locale + +```cshtml {} showLineNumbers + +``` + +```cs {} showLineNumbers +@code { + private BarChart barChart = default!; + private BarChartOptions barChartOptions = default!; + private ChartData chartData = default!; + + protected override void OnInitialized() + { + var colors = ColorBuilder.CategoricalTwelveColors; + + var labels = new List { "Chrome", "Firefox", "Safari", "Edge" }; + var datasets = new List(); + + var dataset1 = new BarChartDataset() + { + Label = "Windows", + Data = new List { 28000, 8000, 2000, 17000 }, + BackgroundColor = new List { colors[0] }, + BorderColor = new List { colors[0] }, + BorderWidth = new List { 0 }, + }; + datasets.Add(dataset1); + + var dataset2 = new BarChartDataset() + { + Label = "macOS", + Data = new List { 8000, 10000, 14000, 8000 }, + BackgroundColor = new List { colors[1] }, + BorderColor = new List { colors[1] }, + BorderWidth = new List { 0 }, + }; + datasets.Add(dataset2); + + var dataset3 = new BarChartDataset() + { + Label = "Other", + Data = new List { 28000, 10000, 14000, 8000 }, + BackgroundColor = new List { colors[2] }, + BorderColor = new List { colors[2] }, + BorderWidth = new List { 0 }, + }; + datasets.Add(dataset3); + + chartData = new ChartData + { + Labels = labels, + Datasets = datasets + }; + + barChartOptions = new(); + barChartOptions.Locale = "de-DE"; + barChartOptions.Responsive = true; + barChartOptions.Interaction = new Interaction { Mode = InteractionMode.Y }; + barChartOptions.IndexAxis = "y"; + + barChartOptions.Scales.X.Title.Text = "Visitors"; + barChartOptions.Scales.X.Title.Display = true; + + barChartOptions.Scales.Y.Title.Text = "Browser"; + barChartOptions.Scales.Y.Title.Display = true; + + barChartOptions.Scales.X.Stacked = true; + barChartOptions.Scales.Y.Stacked = true; + + barChartOptions.Plugins.Title.Text = "Operating system"; + barChartOptions.Plugins.Title.Display = true; + } + + protected override async Task OnAfterRenderAsync(bool firstRender) + { + if (firstRender) + { + await barChart.InitializeAsync(chartData, barChartOptions); + } + await base.OnAfterRenderAsync(firstRender); + } +} +``` + +[See the demo here.](https://demos.blazorbootstrap.com/charts/bar-chart#locale)