Merge pull request #1420 from IgniteUI/arg-dashboard-tile-docs

Initial dashboard tile doc
IgniteUI · Dec 12, 2024 · 0e8b164 · 0e8b164
2 parents 89adb89 + fa4be49
commit 0e8b164
Show file tree

Hide file tree

Showing 3 changed files with 152 additions and 0 deletions.
diff --git a/doc/en/components/dashboard-tile.md b/doc/en/components/dashboard-tile.md
@@ -0,0 +1,149 @@
+---
+title: {Platform} Dashboard Tile Component | {ProductName}
+_description: See how you can easily get started with {Platform} Dashboard Tile Component.
+_keywords: {ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} Dashboard components, {Platform} Dashboard Tile controls
+mentionedTypes: ["Toolbar", "CategoryChart", "XamDataChart", "XamRadialGauge", "XamLinearGauge", "XamGeographicMap"]
+---
+
+# {Platform} Dashboard Tile Overview
+
+The {Platform} Dashboard Tile component is a container control that visualizes an DataSource collection or single data point by generating a data visualization control from the {ProductName} toolset based on the schema of that data. It also uses the `Toolbar` to further interact with and customize these data visualization controls.
+
+## {Platform} Dashboard Tile Example
+
+<!-- TODO -->
+`sample="/charts/dashboard-tile/overview", height="600", alt="{Platform} Dashboard Tile Example"`
+
+## Dependencies
+
+<!-- Angular, WebComponents, React -->
+Install the following packages in the {ProductName} toolset:
+
+```cmd
+npm install {PackageCharts}
+npm install {PackageCore}
+npm install {PackageDashboards}
+npm install {PackageGauges}
+npm install {PackageGrids}
+npm install {PackageInputs}
+npm install {PackageLayouts}
+npm install {PackageMaps}
+```
+
+The following modules are required when using the Dashboard Tile component:
+
+```ts
+import { IgxDashboardTileModule, IgxDataChartDashboardTileModule, IgxRadialGaugeDashboardTileModule,
+         IgxLinearGaugeDashboardTileModule, IgxGeographicMapDashboardTileModule,
+         IgxPieChartDashboardTileModule } from "igniteui-angular-dashboards";
+
+@NgModule({
+    imports: [
+        IgxDataChartDashboardTileModule,
+        IgxRadialGaugeDashboardTileModule,
+        IgxLinearGaugeDashboardTileModule,
+        IgxGeographicMapDashboardTileModule,
+        IgxPieChartDashboardTileModule,
+        IgxDashboardTileModule
+    ]
+})
+export class AppModule {}
+```
+
+```ts
+import { IgrDashboardTileModule, IgrDataChartDashboardTileModule, IgrRadialGaugeDashboardTileModule,
+         IgrLinearGaugeDashboardTileModule, IgrGeographicMapDashboardTileModule,
+         IgrPieChartDashboardTileModule } from "igniteui-react-dashboards";
+
+IgrDataChartDashboardTileModule.register();
+IgrRadialGaugeDashboardTileModule.register();
+IgrLinearGaugeDashboardTileModule.register();
+IgrGeographicMapDashboardTileModule.register();
+IgrPieChartDashboardTileModule.register();
+IgrDashboardTileModule.register();
+```
+
+```ts
+import { IgcDashboardTileModule, IgcDataChartDashboardTileModule, IgcRadialGaugeDashboardTileModule,
+         IgcLinearGaugeDashboardTileModule, IgcGeographicMapDashboardTileModule,
+         IgcPieChartDashboardTileModule } from "igniteui-angular-dashboards";
+
+ModuleManager.register(
+    IgcDataChartDashboardTileModule,
+    IgcRadialGaugeDashboardTileModule,
+    IgcLinearGaugeDashboardTileModule,
+    IgcGeographicMapDashboardTileModule,
+    IgcPieChartDashboardTileModule,
+    IgcDashboardTileModule
+);
+```
+
+<!-- end:Angular, WebComponents, React -->
+
+<!-- Blazor -->
+
+Add the **IgniteUI.Blazor.Controls** namespace in the **_Imports.razor** file:
+
+```razor
+@using IgniteUI.Blazor.Controls
+```
+
+The following modules are required when using the Dashboard Tile component:
+
+```razor
+// in Program.cs file
+
+builder.Services.AddIgniteUIBlazor(
+    typeof(IgbDataChartDashboardTileModule),
+    typeof(IgbRadialGaugeDashboardTileModule),
+    typeof(IgbLinearGaugeDashboardTileModule),
+    typeof(IgbGeographicMapDashboardTileModule),
+    typeof(IgbPieChartDashboardTileModule),
+    typeof(IgbDashboardTileModule)
+);
+```
+
+<!-- end: Blazor -->
+
+## Usage
+
+Depending on what you bind the Dashboard Tile's `DataSource` property to will determine which visualization you see by default, as the control will evaluate the data you bind and then choose a visualization from the {ProductName} toolset to show. The data visualization controls that are included to be shown in the Dashboard Tile are the following:
+
+* [{IgPrefix}CategoryChart](chart-overview.html)
+* [{IgPrefix}DataChart](chart-overview.html)
+* [{IgPrefix}DataPieChart](data-pie-chart.html)
+* [{IgPrefix}GeographicMap](geo-map.html)
+* [{IgPrefix}LinearGauge](linear-gauge.html)
+* [{IgPrefix}RadialGauge](radial-gauge.html)
+
+The data visualization that is chosen by default is mainly dependent on the schema and the count of the `DataSource` that you have bound. For example, if you bind a single numeric value, you will get a `XamRadialGauge`, but if you bind a collection of value-label pairs that are not too close to each other, you will get a `XamDataPieChart`. If you bind an `DataSource` that has more value paths, you will receive a `CategoryChart` or `XamDataChart` with multiple column series or line series, depending mainly on the count of the collection bound. You can also bind to a `ShapeDataSource` to receive a `XamGeographicMap`.
+
+You are not locked into a single visualization when you bind the `DataSource`, and you can tell the control that you want to see a particular visualization by setting its `VisualizationType` property. For example, if you specifically wanted to see a line chart, you could define the Dashboard Tile like so:
+
+<!-- TODO SAMPLE -->
+
+The visualization or properties of the visualization are also configurable using the `Toolbar` at the top of the control. This `Toolbar` has the default tools for the current visualization with the addition of four Dashboard Tile specific ones, highlighted below:
+
+<img src="../images/dashboard-tile-toolbar.png" />
+
+From left to right:
+
+- The first tool will show a data grid with the `DataSource` provided to the control. This is a toggle tool, so if you click it again after showing the grid, it will revert to the visualization.
+- The second tool allows you to configure the properties of the current data visualization.
+- The third tool allows you to change the current visualization, allowing you to plot a different series type or show a different type of visualization altogether. This can be set on the control by setting the `VisualizationType` property, mentioned above.
+- The last tool allows you to configure which properties on your underlying data item are included for the control. You can configure this by setting the `IncludedProperties` or `ExcludedProperties` collection on the control.
+
+## API References
+
+ - `Toolbar`
+ - `CategoryChart`
+ - `XamDataChart`
+ - `DataPieChart`
+ - `XamGeographicMap`
+ - `XamLinearGauge`
+ - `XamRadialGauge`
+
+## Additional Resources
+
+* [{ProductName} **Forums**]({ForumsLink})
+* [{ProductName} **GitHub**]({GithubLink})
diff --git a/doc/en/images/dashboard-tile-toolbar.png b/doc/en/images/dashboard-tile-toolbar.png
diff --git a/docConfig.json b/docConfig.json
@@ -23,6 +23,7 @@
             { "name": "{PackageCommon}",              "value": "igniteui-angular"},
             { "name": "{PackageCore}",                "value": "igniteui-angular-core"},
             { "name": "{PackageCharts}",              "value": "igniteui-angular-charts"},
+            { "name": "{PackageDashboards}",          "value": "igniteui-angular-dashboards"},
             { "name": "{PackageDataSources}",         "value": "igniteui-angular-datasources"},
             { "name": "{PackageExcel}",               "value": "igniteui-angular-excel"},
             { "name": "{PackageGauges}",              "value": "igniteui-angular-gauges"},
@@ -135,6 +136,7 @@
             { "name": "{PackageCommon}",               "value": "igniteui-react"},
             { "name": "{PackageCore}",                 "value": "igniteui-react-core"},
             { "name": "{PackageCharts}",               "value": "igniteui-react-charts"},
+            { "name": "{PackageDashboards}",           "value": "igniteui-react-dashboards"},
             { "name": "{PackageDataSources}",          "value": "igniteui-react-datasources"},
             { "name": "{PackageExcel}",                "value": "igniteui-react-excel"},
             { "name": "{PackageGauges}",               "value": "igniteui-react-gauges"},
@@ -262,6 +264,7 @@
             { "name": "{PackageCommon}",              "value": "igniteui-webcomponents"},
             { "name": "{PackageCore}",                "value": "igniteui-webcomponents-core"},
             { "name": "{PackageCharts}",              "value": "igniteui-webcomponents-charts"},
+            { "name": "{PackageDashboards}",          "value": "igniteui-webcomponents-dashboards"},
             { "name": "{PackageDataSources}",         "value": "igniteui-webcomponents-datasources"},
             { "name": "{PackageExcel}",               "value": "igniteui-webcomponents-excel"},
             { "name": "{PackageGauges}",              "value": "igniteui-webcomponents-gauges"},