Skip to content

Commit fa3afae

Browse files
dimodintacheva
andauthored
docs(pivotgrid): Add PivotGrid documentation (#1486)
* docs(pivotgrid): Add PivotGrid documentation * docs(pivotgrid): PivotGrid documentation scaffolding 2 * PivotGrid next * docs(pivotgrid): More information in Overview and Data Binding * docs(pivotgrid): Further content * docs(pivotgrid): Add a short note * Update components/pivotgrid/data-binding.md Co-authored-by: Nadezhda Tacheva <[email protected]> * docs(pivotgrid): Address PR comments * docs(pivotgrid): Address PR comments 2 --------- Co-authored-by: Nadezhda Tacheva <[email protected]>
1 parent 6209f5e commit fa3afae

File tree

5 files changed

+608
-1
lines changed

5 files changed

+608
-1
lines changed

_config.yml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -248,7 +248,7 @@ navigation:
248248
title: "State Management"
249249
"*how-to":
250250
title: "How To"
251-
"*grid":
251+
"*/grid":
252252
title: "Grid"
253253
"*gridlayout":
254254
title: "Grid Layout"
@@ -479,6 +479,7 @@ intro_columns:
479479
"Grid": "grid-overview"
480480
"ListView": "listview-overview"
481481
"Pager": "pager-overview"
482+
"PivotGrid": "pivotgrid-overview"
482483
"TreeList": "treelist-overview"
483484
-
484485
title: "File Management"

components/pivotgrid/configurator.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Configurator
3+
page_title: PivotGrid Configurator
4+
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.
5+
slug: pivotgrid-configurator
6+
tags: telerik,blazor,pivotgrid
7+
published: True
8+
position: 20
9+
---
10+
11+
# PivotGrid Configurator
12+
13+
This article describes the appearance and behavior of the PivotGrid configurator.
14+
15+
## Sections
16+
17+
The Pivot Grid Configurator contains the following sections:
18+
19+
* [Fields](#fields)
20+
* [Columns](#columns-and-rows)
21+
* [Rows](#columns-and-rows)
22+
* [Values](#values)
23+
* [Buttons](#buttons)
24+
25+
26+
## Fields
27+
28+
**Fields** display in a TreeView with checkboxes. Here is how they work:
29+
30+
* The TreeView items and their checkbox state are populated automatically, based on the PivotGrid data and initial configuration.
31+
* Users can check and uncheck TreeView items, which will add or remove the respective Field in the Columns or Rows sections.
32+
* 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.
33+
* 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.
34+
35+
36+
## Columns and Rows
37+
38+
The **Columns** section of the Configurator shows all fields that are currently used as column headers.
39+
40+
The **Rows** section shows the fields that are used as row headers.
41+
42+
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.
43+
44+
45+
## Values
46+
47+
The **Values** section of the Configurator shows all fields that are currently used as measures (dimensions).
48+
49+
50+
## Buttons
51+
52+
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.
53+
54+
The following user actions do not require users to click on *Apply*:
55+
56+
* Reordering already added fields via dragging
57+
* Sorting
58+
* Filtering
59+
60+
61+
## Example
62+
63+
Refer to the [example of a Pivot Grid using an XMLA Data Provider Type]({%slug pivotgrid-data-binding%}#xmla).
64+
65+
66+
## Next Steps
67+
68+
* [Implement PivotGrid templates]({%slug pivotgrid-templates%})
69+
70+
71+
## See Also
72+
73+
* [Live PivotGrid Demos](https://demos.telerik.com/blazor-ui/pivotgrid)
74+
* [PivotGrid API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikPivotGrid-1)

components/pivotgrid/data-binding.md

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: Data Binding
3+
page_title: PivotGrid Data Binding
4+
description: What are the different ways to provide data to the Telerik UI for Blazor PivotGrid. Information about XMLA datasource, local data.
5+
slug: pivotgrid-data-binding
6+
tags: telerik,blazor,pivotgrid
7+
published: True
8+
position: 10
9+
---
10+
11+
# PivotGrid Data Binding
12+
13+
This article describes the PivotGrid data binding mechanism and the supported data source options.
14+
15+
16+
## Data Provider Type
17+
18+
The PivotGrid supports different data sources via its `DataProviderType` parameter. The parameter type is `PivotGridDataProviderType` enum and its members are:
19+
20+
* [`Local`](#local) (default)
21+
* [`Xmla`](#xmla)
22+
23+
24+
## Local
25+
26+
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).
27+
28+
> Large amounts of local data may impact the performance, especially in WebAssembly applications.
29+
30+
>caption PivotGrid bound to Local data provider
31+
32+
````CSHTML
33+
<TelerikPivotGrid Data="@PivotData">
34+
<PivotGridColumns>
35+
<PivotGridColumn Name="@nameof(PivotModel.City)" />
36+
</PivotGridColumns>
37+
<PivotGridRows>
38+
<PivotGridRow Name="@nameof(PivotModel.Category)" />
39+
<PivotGridRow Name="@nameof(PivotModel.Product)" />
40+
</PivotGridRows>
41+
<PivotGridMeasures>
42+
<PivotGridMeasure Name="@nameof(PivotModel.ContractValue)" />
43+
</PivotGridMeasures>
44+
</TelerikPivotGrid>
45+
46+
@code {
47+
private List<PivotModel> PivotData { get; set; } = new List<PivotModel>();
48+
49+
protected override void OnInitialized()
50+
{
51+
var dataItemCount = 100;
52+
var categoryCount = 3;
53+
var productCount = 5 + 1; // effectively 5, as rnd.Next() will never return 6
54+
var cityCount = 3 + 1; // effectively 3
55+
var rnd = new Random();
56+
57+
for (int i = 1; i <= dataItemCount; i++)
58+
{
59+
var productNumber = rnd.Next(1, productCount);
60+
61+
PivotData.Add(new PivotModel()
62+
{
63+
Category = $"Category {productNumber % categoryCount + 1}",
64+
Product = $"Product {productNumber}",
65+
City = $"City {rnd.Next(1, cityCount)}",
66+
ContractDate = DateTime.Now.AddDays(-rnd.Next(1, 31)).AddMonths(-rnd.Next(1, 12)).AddYears(-rnd.Next(0, 5)),
67+
ContractValue = rnd.Next(123, 987)
68+
});
69+
}
70+
71+
base.OnInitialized();
72+
}
73+
74+
public class PivotModel
75+
{
76+
public string Category { get; set; } = null!;
77+
public string Product { get; set; } = null!;
78+
public string City { get; set; } = null!;
79+
public DateTime ContractDate { get; set; }
80+
public decimal ContractValue { get; set; }
81+
}
82+
}
83+
````
84+
85+
86+
## Xmla
87+
88+
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.
89+
90+
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:
91+
92+
* [`<PivotGridXmlaDataProviderSettings>`](#xmla-data-provider-settings) - configures the data server URL and database name
93+
* [`<PivotGridXmlaDataProviderCredentials>`](#xmla-data-provider-credentials) - configures optional access credentials
94+
95+
### XMLA Data Provider Settings
96+
97+
The `PivotGridXmlaDataProviderSettings` component exposes the following parameters.
98+
99+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
100+
101+
| Parameter | Type | Description |
102+
| --- | --- | --- |
103+
| `Catalog` | `string` | The initial dataset (batabase) name to connect to. |
104+
| `Cube` | `string` | The OLAP cube name. |
105+
| `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). |
106+
107+
>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).
108+
109+
### XMLA Data Provider Credentials
110+
111+
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.
112+
113+
| Parameter | Type | Description |
114+
| --- | --- | --- |
115+
| `Domain` | `string` | (optional) The domain, which verifies the credentials. |
116+
| `Password` | `string` | The password for the provided `Username`. |
117+
| `Username` | `string` | The user that requests access to the XMLA data. |
118+
119+
### XMLA Data Binding Example
120+
121+
>caption PivotGrid bound to XMLA data provider without credentials
122+
123+
````CSHTML
124+
<TelerikPivotGridContainer>
125+
<TelerikPivotGridConfigurator />
126+
127+
<TelerikPivotGridConfiguratorButton />
128+
129+
<TelerikPivotGrid DataProviderType="@PivotGridDataProviderType.Xmla"
130+
TItem="object">
131+
<PivotGridSettings>
132+
<PivotGridXmlaDataProviderSettings ServerUrl="https://demos.telerik.com/olap/msmdpump.dll"
133+
Catalog="Adventure Works DW 2008R2"
134+
Cube="Adventure Works" />
135+
</PivotGridSettings>
136+
137+
<PivotGridRows>
138+
<PivotGridRow Name="[Product].[Category]"></PivotGridRow>
139+
<PivotGridRow Name="[Product].[Model Name]"></PivotGridRow>
140+
</PivotGridRows>
141+
142+
<PivotGridColumns>
143+
<PivotGridColumn Name="[Date].[Calendar Quarter of Year]"></PivotGridColumn>
144+
<PivotGridColumn Name="[Date].[Calendar Year]"></PivotGridColumn>
145+
</PivotGridColumns>
146+
147+
<PivotGridMeasures>
148+
<PivotGridMeasure Name="[Measures].[Reseller Order Count]"></PivotGridMeasure>
149+
</PivotGridMeasures>
150+
</TelerikPivotGrid>
151+
</TelerikPivotGridContainer>
152+
````
153+
154+
## See Also
155+
156+
* [Live PivotGrid Demos - Local Data Binding](https://demos.telerik.com/blazor-ui/pivotgrid/local-data-binding)
157+
* [Live PivotGrid Demos - OLAP (XMLA) Data Binding](https://demos.telerik.com/blazor-ui/pivotgrid/xmla-data-binding)
158+
* [PivotGrid API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikPivotGrid-1)

0 commit comments

Comments
 (0)