Skip to content

Commit 0ecdb7b

Browse files
github-actions[bot]NansiYanchevayordan-mitevdimodi
authored
Merge common-article-descriptors-2416 into production (#2467)
* docs(common):Create common article for descriptors * Update components/gantt/gantt-tree/filter/overview.md Co-authored-by: Yordan <[email protected]> * revamp by adding all descriptors * revamp main and refer related articles * update common article * Update common-features/data-binding/descriptors.md Co-authored-by: Dimo Dimov <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Dimo Dimov <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Dimo Dimov <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Dimo Dimov <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/filter/overview.md Co-authored-by: Dimo Dimov <[email protected]> * update after review * update after support review * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * Update common-features/data-binding/descriptors.md Co-authored-by: Yordan <[email protected]> * update after tech writer review --------- Co-authored-by: NansiYancheva <[email protected]> Co-authored-by: NansiYancheva <[email protected]> Co-authored-by: Yordan <[email protected]> Co-authored-by: Dimo Dimov <[email protected]>
1 parent f566c32 commit 0ecdb7b

File tree

24 files changed

+417
-59
lines changed

24 files changed

+417
-59
lines changed

‎common-features/data-binding/cloud-services.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: How to data bind Telerik Blazor components to cloud data services s
55
slug: common-features-data-binding-cloud
66
tags: telerik,blazor,binding,databinding,cloud
77
published: True
8-
position: 15
8+
position: 30
99
---
1010

1111
# Databinding to Cloud Services

‎common-features/data-binding/descriptors.md‎

Lines changed: 343 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,343 @@
1+
---
2+
title: Descriptors - FilterDescriptor, SearchFilter, SortDescriptor, GroupDescriptor
3+
page_title: Descriptors - FilterDescriptor, SearchFilter, SortDescriptor, GroupDescriptor
4+
description: Discover the FilterDescriptor, SortDescriptor, SearchFilter and GroupDescriptor properties and how to access their values.
5+
slug: common-features-descriptors
6+
tags: telerik,blazor,filterdescriptor, sortdescriptor, groupdescriptor, searchfilter
7+
published: True
8+
position: 10
9+
---
10+
11+
12+
## Data Operation Descriptors
13+
14+
This article explains how to retrieve the applied filtering, searching, sorting, and grouping criteria in Blazor components. The article applies to components that support these features. The components that offer one or all of the functionalities are:
15+
16+
* Components that [expose an `OnRead` event]({%slug common-features-data-binding-onread%}#components-with-onread-event), excluding the [ListView]({%slug listview-overview%}), because the ListView doesn't support built-in filtering, searching, sorting, and grouping.
17+
* [Filter]({%slug filter-overview%})
18+
* [Gantt]({%slug gantt-overview%})
19+
* [TreeList]({%slug treelist-overview%})
20+
21+
## Get Sort, Filter, Group, and Search Descriptors
22+
23+
You can obtain the applied filtering, searching, sorting, and grouping criteria in two ways:
24+
25+
* [Through the OnRead Event](#through-the-onread-event)
26+
* [Through the Component's State](#through-the-component-state)
27+
28+
### Through the OnRead Event
29+
30+
Use the [`Request` property]({%slug common-features-data-binding-onread%}#event-argument) of the [`OnRead` event argument object](/blazor-ui/api/Telerik.Blazor.Components.ReadEventArgs):
31+
32+
````CS
33+
async Task OnReadHandler(...ReadEventArgs args)
34+
{
35+
// Get the applied filtering and searching criteria.
36+
// args.Request.Filters
37+
38+
// Get the applied grouping criteria, including:
39+
// *The field by which the user groups.
40+
// *The sort direction of the groups ordering.
41+
// args.Request.Groups
42+
43+
// Get the applied sorting criteria, including:
44+
// *The field which the user sorts.
45+
// *The sort direction.
46+
// args.Request.Sorts
47+
}
48+
````
49+
50+
See the [complete example](#example-with-onread-event-handler) at the bottom of the article.
51+
52+
### Through the Component State
53+
54+
Use the component's state property of the `OnStateChanged` event argument. This approach applies to the Gantt, Grid, and TreeList because they expose the state feature. For example:
55+
56+
````CS
57+
async Task OnStateChangedHandler(GridStateEventArgs<Product> args)
58+
{
59+
// Get the applied filtering criteria.
60+
// args.GridState.FilterDescriptors
61+
62+
// Get the applied searching criteria.
63+
// args.GridState.SearchFilter
64+
65+
// Get the applied grouping criteria, including:
66+
// *The field by which the user groups.
67+
// *The sort direction of the groups ordering.
68+
// args.GridState.GroupDescriptors
69+
70+
// Get the applied sorting criteria, including:
71+
// *The field which the user sorts.
72+
// *The sort direction.
73+
// args.GridState.SortDescriptors
74+
}
75+
````
76+
77+
See the [complete example](#example-with-component-state) at the bottom of the article.
78+
79+
80+
## Filtering
81+
82+
The `args.Request.Filters` and the `args....State.FilterDescriptors` are collections of [`IFilterDescriptor`](/blazor-ui/api/Telerik.DataSource.IFilterDescriptor). To access the filtering criteria, such as the user input to filter by, cast each `IFilterDescriptor` from the respective collection:
83+
84+
* If the component is of type input or select, such as the AutoComplete, ComboBox, DropDownList, MultiColumnComboBox, MultiSelect, cast the first `IFilterDescriptor` from the collection to [`FilterDescriptor`](/blazor-ui/api/telerik.datasource.filterdescriptor).
85+
* Otherwise, cast each `IFilterDescriptor` from the `args.Request.Filters` collection, respectively from the `args....State.FilterDescriptors` collection, to [`CompositeFilterDescriptor`](/blazor-ui/api/Telerik.DataSource.CompositeFilterDescriptor).
86+
87+
### CompositeFilterDescriptor
88+
89+
The `CompositeFilterDescriptor` exposes:
90+
91+
* The [`FilterDescriptors`](/blazor-ui/api/telerik.datasource.compositefilterdescriptor#Telerik_DataSource_CompositeFilterDescriptor_FilterDescriptors) property. This property represents another collection of `IFilterDescriptor`. To access the filtering criteria, cast each `IFilterDescriptor` to a `FilterDescriptor`. When the Filter component gets groupable filtering, cast each `IFilterDescriptor` to another `CompositeFilterDescriptor`.
92+
* The [`LogicalOperator`](/blazor-ui/api/telerik.datasource.compositefilterdescriptor#Telerik_DataSource_CompositeFilterDescriptor_LogicalOperator) property. This property can be either `AND` or `OR`. This property represents the logical operator applied between the instances in the `FilterDescriptors` collection.
93+
94+
When the filtering is initiated, the `CompositeFilterDescriptor` properties get different values depending on the filter mode:
95+
96+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
97+
98+
| Filter Mode | FilterDescriptors Property Value | LogicalOperator Property Value |
99+
| --- | --- | --- |
100+
| `FilterMenu` | Two filter descriptor instances for each filtered field. Each filter descriptor instance gets the user input as `Value`. If there is no user input in one of the input fields in the menu, then this filter descriptor instance `Value` is null. | Depending on the user's choice. |
101+
| `FilterRow` | Two filter descriptor instances for each filtered field. The second filter descriptor instance always gets null as `Value`, because there is no second input field. | AND |
102+
103+
104+
## Searching
105+
106+
The searching criteria in a Grid or TreeList are stored in an individual `IFilterDescriptor`. Cast it to [`CompositeFilterDescriptor`](#compositefilterdescriptor). The `CompositeFilterDescriptor` holds one child `FilterDescriptor` for each searchable string column. Each `FilterDescriptor` has the same `Value`, which is the user's search input. The value of the `LogicalOperator` property of the `CompositeFilterDescriptor` is `OR`.
107+
108+
109+
## Sorting
110+
111+
The sorting criteria in a Grid, TreeList or Gantt are stored in a collection of [`SortDescriptor`](/blazor-ui/api/telerik.datasource.sortdescriptor) objects. Each `SortDescriptor` instance gives access to:
112+
* The `Member`&mdash;The field where the user sorts.
113+
* The `SortDirection`&mdash;The sort direction for this sort descriptor.
114+
115+
When the [`SortMode`](/blazor-ui/api/Telerik.Blazor.SortMode) is `Multiple`, you may need to consider the order of the `SortDescriptor` instances. The first applied sorting criteria take precedence over all others. If there are equal values in the first sorted items, then those items are sorted by the following sorting criteria.
116+
117+
118+
## Grouping
119+
120+
Тhe grouping criteria for each group are stored in an individual collection of [`GroupDescriptor`](/blazor-ui/api/telerik.datasource.groupdescriptor) objects. The `GroupDescriptor` class inherits the `SortDescriptor` class and gives access to the same properties as the `SortDescriptor` class.
121+
122+
The user may group by multiple fields. The groups for subsequent fields will be nested within their parent groups. The grouping criteria from the parent group are stored in the first `GroupDescriptor` instance from the collection.
123+
124+
125+
## Example with OnRead Event Handler
126+
127+
You can obtain the FilterDescriptor, SortDescriptor, and GroupDescriptor in the `OnRead` event handler.
128+
129+
````CSHTML
130+
@using Telerik.DataSource
131+
@using Telerik.DataSource.Extensions
132+
133+
<p>@ConsoleSim</p>
134+
135+
<TelerikGrid TItem="@SampleData"
136+
OnRead="@OnReadHandler"
137+
Sortable="true"
138+
Groupable="true"
139+
FilterMode="@GridFilterMode.FilterMenu"
140+
Pageable="true" PageSize="15"
141+
Height="400px">
142+
<GridToolBarTemplate>
143+
<GridSearchBox />
144+
</GridToolBarTemplate>
145+
<GridColumns>
146+
<GridColumn Field="@nameof(SampleData.Id)" />
147+
<GridColumn Field="@nameof(SampleData.Name)" />
148+
<GridColumn Field="@nameof(SampleData.Team)" />
149+
<GridColumn Field="@nameof(SampleData.HireDate)" />
150+
</GridColumns>
151+
</TelerikGrid>
152+
153+
154+
@code {
155+
private MarkupString ConsoleSim { get; set; } //To showcase what you get.
156+
157+
private async Task OnReadHandler(GridReadEventArgs args)
158+
{
159+
string output = string.Empty;
160+
161+
//Get the filtering and searching criteria.
162+
output += "<span><strong>FILTERS:</strong><span></br>";
163+
foreach (var item in args.Request.Filters)
164+
{
165+
if (item is CompositeFilterDescriptor)
166+
{
167+
CompositeFilterDescriptor currFilter = (CompositeFilterDescriptor)item;
168+
output += $"START nested filter: Logical operator: {currFilter.LogicalOperator}, details:<br />";
169+
foreach (FilterDescriptor nestedFilter in currFilter.FilterDescriptors)
170+
{
171+
output += $"Filtered field: {nestedFilter.Member}, Filter operator: {nestedFilter.Operator}, Filter value: {nestedFilter.Value}<br />";
172+
}
173+
output += "END nested filter<br />";
174+
}
175+
}
176+
177+
//Get the sorting criteria.
178+
output += "<span><strong>SORTS:</strong><span></br>";
179+
foreach (SortDescriptor item in args.Request.Sorts)
180+
{
181+
output += $"Sorted field: {item.Member}, Sort direction: {item.SortDirection} <br />";
182+
}
183+
184+
//Get the grouping criteria.
185+
output += "<span><strong>GROUPS:</strong><span></br>";
186+
foreach (GroupDescriptor item in args.Request.Groups)
187+
{
188+
output += $"Grouped field: {item.Member}, Group sort direction: {item.SortDirection} <br />";
189+
}
190+
191+
ConsoleSim = new MarkupString(output);
192+
193+
var result = PristineData.ToDataSourceResult(args.Request);
194+
195+
args.Data = result.Data;
196+
args.Total = result.Total;
197+
}
198+
199+
private IEnumerable<SampleData> PristineData = Enumerable.Range(1, 300).Select(x => new SampleData
200+
{
201+
Id = x,
202+
Name = "name " + x,
203+
Team = "team " + x % 5,
204+
HireDate = DateTime.Now.AddDays(-x).Date
205+
});
206+
207+
public class SampleData
208+
{
209+
public int Id { get; set; }
210+
public string Name { get; set; }
211+
public string Team { get; set; }
212+
public DateTime HireDate { get; set; }
213+
}
214+
}
215+
````
216+
217+
## Example with Component State
218+
219+
You can obtain the FilterDescriptor, SearchFilter, SortDescriptor, and GroupDescriptor through the component's state.
220+
221+
````CSHTML
222+
@using System.Text.Json
223+
@using Telerik.DataSource
224+
225+
<p>@ConsoleSim</p>
226+
227+
<TelerikGrid Data="@GridData"
228+
Sortable="true"
229+
Groupable="true"
230+
FilterMode="@GridFilterMode.FilterMenu"
231+
Pageable="true" PageSize="15"
232+
Height="400px"
233+
OnStateChanged="@( (GridStateEventArgs<Product> args) => OnGridStateChanged(args) )">
234+
<GridToolBarTemplate>
235+
<GridSearchBox />
236+
</GridToolBarTemplate>
237+
<GridColumns>
238+
<GridColumn Field="@nameof(Product.Name)" />
239+
<GridColumn Field="@nameof(Product.Category)" />
240+
<GridColumn Field="@nameof(Product.Stock)" />
241+
<GridColumn Field="@nameof(Product.Discontinued)" />
242+
</GridColumns>
243+
</TelerikGrid>
244+
245+
@code {
246+
private MarkupString ConsoleSim { get; set; }
247+
248+
private List<Product> GridData { get; set; } = new List<Product>();
249+
250+
private async Task OnGridStateChanged(GridStateEventArgs<Product> args)
251+
{
252+
string output = string.Empty;
253+
254+
//Get the searching criteria.
255+
output += "<span><strong>SEARCHING:</strong><span></br>";
256+
var searching = args.GridState.SearchFilter;
257+
258+
if (searching is CompositeFilterDescriptor)
259+
{
260+
CompositeFilterDescriptor currSearch = searching as CompositeFilterDescriptor;
261+
output += $"START nested searching: Logical operator: {currSearch.LogicalOperator}, details:<br />";
262+
foreach (FilterDescriptor nestedSearch in currSearch.FilterDescriptors)
263+
{
264+
output += $"Search field: {nestedSearch.Member}, Search operator {nestedSearch.Operator}, Search value: {nestedSearch.Value}<br />";
265+
}
266+
output += "END nested searching<br />";
267+
}
268+
269+
270+
//Get the filtering criteria.
271+
output += "<span><strong>FILTERS:</strong><span></br>";
272+
273+
foreach (var item in args.GridState.FilterDescriptors)
274+
{
275+
if (item is CompositeFilterDescriptor)
276+
{
277+
CompositeFilterDescriptor currFilter = item as CompositeFilterDescriptor;
278+
output += $"START nested filter: Logical operator: {currFilter.LogicalOperator}, details:<br />";
279+
foreach (FilterDescriptor nestedFilter in currFilter.FilterDescriptors)
280+
{
281+
output += $"Filtered field: {nestedFilter.Member}, Filter operator: {nestedFilter.Operator}, Filter value: {nestedFilter.Value}<br />";
282+
}
283+
output += "END nested filter<br />";
284+
}
285+
}
286+
287+
//Get the sorting criteria.
288+
output += "<span><strong>SORTS:</strong><span></br>";
289+
foreach (SortDescriptor item in args.GridState.SortDescriptors)
290+
{
291+
output += $"Sorted field: {item.Member}, Sort direction: {item.SortDirection} <br />";
292+
}
293+
294+
//Get the grouping criteria.
295+
output += "<span><strong>GROUPS:</strong><span></br>";
296+
foreach (SortDescriptor item in args.GridState.GroupDescriptors)
297+
{
298+
output += $"Grouped field: {item.Member}, Group sort direction: {item.SortDirection} <br />";
299+
}
300+
301+
ConsoleSim = new MarkupString(output);
302+
}
303+
304+
protected override void OnInitialized()
305+
{
306+
var rnd = new Random();
307+
308+
for (int i = 1; i <= 12; i++)
309+
{
310+
GridData.Add(new Product()
311+
{
312+
Id = i,
313+
Name = $"Product {i}",
314+
Category = $"Category {i % 4 + 1}",
315+
Stock = rnd.Next(0, 100),
316+
Discontinued = i % 3 == 0
317+
});
318+
}
319+
}
320+
321+
public class Product
322+
{
323+
public int Id { get; set; }
324+
public string Name { get; set; } = string.Empty;
325+
public string Category { get; set; } = string.Empty;
326+
public int Stock { get; set; }
327+
public bool Discontinued { get; set; }
328+
}
329+
}
330+
````
331+
332+
## See Also
333+
334+
* [AutoComplete OnRead Event]({%slug autocomplete-events%}#onread)
335+
* [ComboBox OnRead Event]({%slug components/combobox/events%}#onread)
336+
* [DropDownList OnRead Event]({%slug components/dropdownlist/events%}#onread)
337+
* [Filter Overview]({%slug filter-overview%})
338+
* [Gantt State]({%slug gantt-state%})
339+
* [Grid OnRead Event]({%slug components/grid/manual-operations%})
340+
* [Grid State]({%slug grid-state%})
341+
* [MultiColumnComboBox OnRead Event]({%slug multicolumncombobox-events%}#onread)
342+
* [MultiSelect OnRead Event]({%slug multiselect-events%}#onread)
343+
* [TreeList State]({%slug treelist-state%})

‎common-features/filter-operators.md‎ renamed to ‎common-features/data-binding/filter-operators.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Supported Filter Operators in the Telerik UI for Blazor component s
55
slug: common-features-filter-operators
66
tags: telerik,blazor,filter,operator
77
published: True
8-
position: 10
8+
position: 15
99
---
1010

1111
# Filter Operators

‎common-features/data-binding/observable-data.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ slug: common-features-observable-data
66
tags: telerik,blazor,observable,data,live,INotifyCollectionChanged
77
published: True
88
previous_url: /common-features/observable-data
9-
position: 10
9+
position: 25
1010
---
1111

1212
# Observable Data and Refresh Data

‎common-features/telerik-datasource-package.md‎ renamed to ‎common-features/data-binding/telerik-datasource-package.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Details about the Telerik.DataSource NuGet package that come with T
55
slug: common-features-datasource-package
66
tags: telerik,blazor,data,source,package
77
published: True
8-
position: 50
8+
position: 20
99
---
1010

1111
# Telerik DataSource Package

0 commit comments

Comments
 (0)