docs(pivotgrid): Add PivotGrid documentation #1486
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,74 @@ | ||||||
| --- | ||||||
| title: Configurator | ||||||
| page_title: PivotGrid Configurator | ||||||
| description: The PivotGrid configurator allows end users to control the fields, columns, rows and values (measures), which the Telerik UI for Blazor PivotGrid will show. | ||||||
| slug: pivotgrid-configurator | ||||||
| tags: telerik,blazor,pivotgrid | ||||||
| published: True | ||||||
| position: 20 | ||||||
| --- | ||||||
| | ||||||
| # PivotGrid Configurator | ||||||
| | ||||||
| This article describes the appearance and behavior of the PivotGrid configurator. | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| | ||||||
| ## Sections | ||||||
| | ||||||
| The Pivot Grid Configurator contains the following sections: | ||||||
| | ||||||
| * [Fields](#fields) | ||||||
| * [Columns](#columns-and-rows) | ||||||
| * [Rows](#columns-and-rows) | ||||||
| * [Values](#values) | ||||||
| * [Buttons](#buttons) | ||||||
| | ||||||
| | ||||||
| ## Fields | ||||||
| | ||||||
| **Fields** display in a TreeView with checkboxes. Here is how they work: | ||||||
| There was a problem hiding this comment. "Display" requires an object. Suggested change
| ||||||
| | ||||||
| * The TreeView items and their checkbox state are populated automatically, based on the PivotGrid data and initial configuration. | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| * Users can check and uncheck TreeView items, which will add or remove the respective Field in the Columns or Rows sections. | ||||||
| * If a field is defined in a `<PivotGridRow>` or `<PivotGridColumn>` tag in the Pivot Grid, then users cannot use that field in another Configurator section. | ||||||
| * If a field is not defined anywhere in the PivotGrid declaration, then checking a TreeView checkbox will add it as a *column field*. Then, the user can drag it to another section. | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| | ||||||
| | ||||||
| ## Columns and Rows | ||||||
| | ||||||
| The **Columns** section of the Configurator shows all fields that are currently used as column headers. | ||||||
| There was a problem hiding this comment. Don't use bold for the terms. | ||||||
| | ||||||
| The **Rows** section shows the fields that are used as row headers. | ||||||
| | ||||||
| The Row and Column fields support sorting and filtering of the field values. User should click the three dots in each chip to open a context menu with these options. | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| | ||||||
| | ||||||
| ## Values | ||||||
| | ||||||
| The **Values** section of the Configurator shows all fields that are currently used as measures (dimensions). | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| | ||||||
| | ||||||
| ## Buttons | ||||||
| | ||||||
| The bottom section of the Configurator renders *Apply* and *Cancel* buttons. End users should click them after adding or removing fields to the Columns, Rows and Values sections. | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| | ||||||
| The following user actions do not require users to click on *Apply*: | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| | ||||||
| * Reordering already added fields via dragging | ||||||
| * Sorting | ||||||
| * Filtering | ||||||
| | ||||||
| | ||||||
| ## Example | ||||||
| | ||||||
| Refer to the [example of a Pivot Grid using an XMLA Data Provider Type]({%slug pivotgrid-data-binding%}#xmla). | ||||||
| | ||||||
| | ||||||
| ## Next Steps | ||||||
| | ||||||
| * [Implement PivotGrid templates]({%slug pivotgrid-templates%}) | ||||||
| | ||||||
| | ||||||
| ## See Also | ||||||
| | ||||||
| * [Live PivotGrid Demos](https://demos.telerik.com/blazor-ui/pivotgrid) | ||||||
| * [PivotGrid API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikPivotGrid-1) | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,158 @@ | ||||||
| --- | ||||||
| title: Data Binding | ||||||
| page_title: PivotGrid Data Binding | ||||||
| description: What are the different ways to provide data to the Telerik UI for Blazor PivotGrid. Information about XMLA datasource, local data. | ||||||
| There was a problem hiding this comment. Suggested change
| ||||||
| slug: pivotgrid-data-binding | ||||||
| tags: telerik,blazor,pivotgrid | ||||||
| published: True | ||||||
| position: 10 | ||||||
| --- | ||||||
| | ||||||
| # PivotGrid Data Binding | ||||||
| | ||||||
| This article describes the PivotGrid data binding mechanism and the supported data source options. | ||||||
| | ||||||
| | ||||||
| ## Data Provider Type | ||||||
| | ||||||
| The PivotGrid supports different data sources via its `DataProviderType` parameter. The parameter type is `PivotGridDataProviderType` enum and its members are: | ||||||
| | ||||||
| * [`Local`](#local) (default) | ||||||
| * [`Xmla`](#xmla) | ||||||
| | ||||||
| | ||||||
| ## Local | ||||||
| | ||||||
| When bound to local data, the Pivot Grid requires its `Data` parameter to provide all the data at once as `IEnumerable<TItem>`. The component will perform all aggregate calculations in-memory and there is no [load on demand]({%slug pivotgrid-overview%}#pivotgrid-parameters). | ||||||
| | ||||||
| > Large amounts of local data may impact the performance, especially in WebAssembly applications. | ||||||
| | ||||||
| >caption PivotGrid bound to Local data provider | ||||||
| | ||||||
| ````CSHTML | ||||||
| <TelerikPivotGrid Data="@PivotData"> | ||||||
| <PivotGridColumns> | ||||||
| <PivotGridColumn Name="@nameof(PivotModel.City)" /> | ||||||
| </PivotGridColumns> | ||||||
| <PivotGridRows> | ||||||
| <PivotGridRow Name="@nameof(PivotModel.Category)" /> | ||||||
| <PivotGridRow Name="@nameof(PivotModel.Product)" /> | ||||||
| </PivotGridRows> | ||||||
| <PivotGridMeasures> | ||||||
| <PivotGridMeasure Name="@nameof(PivotModel.ContractValue)" /> | ||||||
| </PivotGridMeasures> | ||||||
| </TelerikPivotGrid> | ||||||
| | ||||||
| @code { | ||||||
| private List<PivotModel> PivotData { get; set; } = new List<PivotModel>(); | ||||||
| | ||||||
| protected override void OnInitialized() | ||||||
| { | ||||||
| var dataItemCount = 100; | ||||||
| var categoryCount = 3; | ||||||
| var productCount = 5 + 1; // effectively 5, as rnd.Next() will never return 6 | ||||||
| var cityCount = 3 + 1; // effectively 3 | ||||||
| var rnd = new Random(); | ||||||
| | ||||||
| for (int i = 1; i <= dataItemCount; i++) | ||||||
| { | ||||||
| var productNumber = rnd.Next(1, productCount); | ||||||
| | ||||||
| PivotData.Add(new PivotModel() | ||||||
| { | ||||||
| Category = $"Category {productNumber % categoryCount + 1}", | ||||||
| Product = $"Product {productNumber}", | ||||||
| City = $"City {rnd.Next(1, cityCount)}", | ||||||
| ContractDate = DateTime.Now.AddDays(-rnd.Next(1, 31)).AddMonths(-rnd.Next(1, 12)).AddYears(-rnd.Next(0, 5)), | ||||||
| ContractValue = rnd.Next(123, 987) | ||||||
| }); | ||||||
| } | ||||||
| | ||||||
| base.OnInitialized(); | ||||||
| } | ||||||
| | ||||||
| public class PivotModel | ||||||
| { | ||||||
| public string Category { get; set; } = null!; | ||||||
| public string Product { get; set; } = null!; | ||||||
| public string City { get; set; } = null!; | ||||||
| public DateTime ContractDate { get; set; } | ||||||
| public decimal ContractValue { get; set; } | ||||||
| } | ||||||
| } | ||||||
| ```` | ||||||
| | ||||||
| | ||||||
| ## Xmla | ||||||
| | ||||||
| The PivotGrid supports binding to [XML for Analysis](https://learn.microsoft.com/en-us/analysis-services/xmla/xml-for-analysis-xmla-reference) data, for example an [OLAP cube](https://en.wikipedia.org/wiki/OLAP_cube). For more information about OLAP cubes, check [Just What Are Cubes Anyway? A Painless Introduction to OLAP Technology](https://learn.microsoft.com/en-us/previous-versions/office/developer/office-xp/aa140038(v=office.10)) by Microsoft. | ||||||
| | ||||||
| The PivotGrid provides nested Razor components to setup the XMLA connection. Use the `<PivotGridSettings>` tag and place one or both of the following inside it: | ||||||
| | ||||||
| * [`<PivotGridXmlaDataProviderSettings>`](#xmla-data-provider-settings) - configures the data server URL and database name | ||||||
| There was a problem hiding this comment. Use an em dash in definition lists. | ||||||
| * [`<PivotGridXmlaDataProviderCredentials>`](#xmla-data-provider-credentials) - configures optional access credentials | ||||||
| | ||||||
| ### XMLA Data Provider Settings | ||||||
| | ||||||
| The `PivotGridXmlaDataProviderSettings` component exposes the following parameters. | ||||||
| | ||||||
| @[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) | ||||||
| | ||||||
| | Parameter | Type | Description | | ||||||
| | --- | --- | --- | | ||||||
| | `Catalog` | `string` | The initial dataset (batabase) name to connect to. | | ||||||
| | `Cube` | `string` | The OLAP cube name. | | ||||||
| | `ServerUrl` | `string` | The endpoint URL that provides [HTTP access to the XMLA Analysis Services](https://learn.microsoft.com/en-us/analysis-services/instances/configure-http-access-to-analysis-services-on-iis-8-0). If the endpoint is on a different domain, make sure to [configure CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). | | ||||||
| | ||||||
| >tip Setting up an OLAP cube is outside the scope of this documentation. You can start from [SQL Server Analysis Services](https://learn.microsoft.com/en-us/analysis-services/ssas-overview). | ||||||
| | ||||||
| ### XMLA Data Provider Credentials | ||||||
| | ||||||
| The `<PivotGridXmlaDataProviderCredentials>` component creates an object, which is similar to [`System.Net.NetworkCredential`](https://learn.microsoft.com/en-us/dotnet/api/system.net.networkcredential) and works in a similar way. It has the following parameters. | ||||||
| | ||||||
| | Parameter | Type | Description | | ||||||
| | --- | --- | --- | | ||||||
| | `Domain` | `string` | (optional) The domain, which verifies the credentials. | | ||||||
| | `Password` | `string` | The password for the provided `Username`. | | ||||||
| | `Username` | `string` | The user that requests access to the XMLA data. | | ||||||
| | ||||||
| ### XMLA Data Binding Example | ||||||
| | ||||||
| >caption PivotGrid bound to XMLA data provider without credentials | ||||||
| | ||||||
| ````CSHTML | ||||||
| <TelerikPivotGridContainer> | ||||||
| <TelerikPivotGridConfigurator /> | ||||||
| | ||||||
| <TelerikPivotGridConfiguratorButton /> | ||||||
| | ||||||
| <TelerikPivotGrid DataProviderType="@PivotGridDataProviderType.Xmla" | ||||||
| TItem="object"> | ||||||
| <PivotGridSettings> | ||||||
| <PivotGridXmlaDataProviderSettings ServerUrl="https://demos.telerik.com/olap/msmdpump.dll" | ||||||
| Catalog="Adventure Works DW 2008R2" | ||||||
| Cube="Adventure Works" /> | ||||||
| </PivotGridSettings> | ||||||
| | ||||||
| <PivotGridRows> | ||||||
| <PivotGridRow Name="[Product].[Category]"></PivotGridRow> | ||||||
| <PivotGridRow Name="[Product].[Model Name]"></PivotGridRow> | ||||||
| </PivotGridRows> | ||||||
| | ||||||
| <PivotGridColumns> | ||||||
| <PivotGridColumn Name="[Date].[Calendar Quarter of Year]"></PivotGridColumn> | ||||||
| <PivotGridColumn Name="[Date].[Calendar Year]"></PivotGridColumn> | ||||||
| </PivotGridColumns> | ||||||
| | ||||||
| <PivotGridMeasures> | ||||||
| <PivotGridMeasure Name="[Measures].[Reseller Order Count]"></PivotGridMeasure> | ||||||
| </PivotGridMeasures> | ||||||
| </TelerikPivotGrid> | ||||||
| </TelerikPivotGridContainer> | ||||||
| ```` | ||||||
| | ||||||
| ## See Also | ||||||
| | ||||||
| * [Live PivotGrid Demos - Local Data Binding](https://demos.telerik.com/blazor-ui/pivotgrid/local-data-binding) | ||||||
| * [Live PivotGrid Demos - OLAP (XMLA) Data Binding](https://demos.telerik.com/blazor-ui/pivotgrid/xmla-data-binding) | ||||||
| * [PivotGrid API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikPivotGrid-1) | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.