diff --git a/common-features/data-binding/cloud-services.md b/common-features/data-binding/cloud-services.md index 1d902149f5..de14435860 100644 --- a/common-features/data-binding/cloud-services.md +++ b/common-features/data-binding/cloud-services.md @@ -5,7 +5,7 @@ description: How to data bind Telerik Blazor components to cloud data services s slug: common-features-data-binding-cloud tags: telerik,blazor,binding,databinding,cloud published: True -position: 15 +position: 30 --- # Databinding to Cloud Services diff --git a/common-features/data-binding/descriptors.md b/common-features/data-binding/descriptors.md new file mode 100644 index 0000000000..96883ecd8b --- /dev/null +++ b/common-features/data-binding/descriptors.md @@ -0,0 +1,343 @@ +--- +title: Descriptors - FilterDescriptor, SearchFilter, SortDescriptor, GroupDescriptor +page_title: Descriptors - FilterDescriptor, SearchFilter, SortDescriptor, GroupDescriptor +description: Discover the FilterDescriptor, SortDescriptor, SearchFilter and GroupDescriptor properties and how to access their values. +slug: common-features-descriptors +tags: telerik,blazor,filterdescriptor, sortdescriptor, groupdescriptor, searchfilter +published: True +position: 10 +--- + + +## Data Operation Descriptors + +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: + +* 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. +* [Filter]({%slug filter-overview%}) +* [Gantt]({%slug gantt-overview%}) +* [TreeList]({%slug treelist-overview%}) + +## Get Sort, Filter, Group, and Search Descriptors + +You can obtain the applied filtering, searching, sorting, and grouping criteria in two ways: + +* [Through the OnRead Event](#through-the-onread-event) +* [Through the Component's State](#through-the-component-state) + +### Through the OnRead Event + +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): + +````CS +async Task OnReadHandler(...ReadEventArgs args) +{ + // Get the applied filtering and searching criteria. + // args.Request.Filters + + // Get the applied grouping criteria, including: + // *The field by which the user groups. + // *The sort direction of the groups ordering. + // args.Request.Groups + + // Get the applied sorting criteria, including: + // *The field which the user sorts. + // *The sort direction. + // args.Request.Sorts +} +```` + +See the [complete example](#example-with-onread-event-handler) at the bottom of the article. + +### Through the Component State + +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: + +````CS +async Task OnStateChangedHandler(GridStateEventArgs args) +{ + // Get the applied filtering criteria. + // args.GridState.FilterDescriptors + + // Get the applied searching criteria. + // args.GridState.SearchFilter + + // Get the applied grouping criteria, including: + // *The field by which the user groups. + // *The sort direction of the groups ordering. + // args.GridState.GroupDescriptors + + // Get the applied sorting criteria, including: + // *The field which the user sorts. + // *The sort direction. + // args.GridState.SortDescriptors +} +```` + +See the [complete example](#example-with-component-state) at the bottom of the article. + + +## Filtering + +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: + +* 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). +* 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). + +### CompositeFilterDescriptor + +The `CompositeFilterDescriptor` exposes: + +* 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`. +* 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. + +When the filtering is initiated, the `CompositeFilterDescriptor` properties get different values depending on the filter mode: + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Filter Mode | FilterDescriptors Property Value | LogicalOperator Property Value | +| --- | --- | --- | +| `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. | +| `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 | + + +## Searching + +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`. + + +## Sorting + +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: +* The `Member`—The field where the user sorts. +* The `SortDirection`—The sort direction for this sort descriptor. + +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. + + +## Grouping + +Т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. + +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. + + +## Example with OnRead Event Handler + +You can obtain the FilterDescriptor, SortDescriptor, and GroupDescriptor in the `OnRead` event handler. + +````CSHTML +@using Telerik.DataSource +@using Telerik.DataSource.Extensions + +

@ConsoleSim

+ + + + + + + + + + + + + + +@code { + private MarkupString ConsoleSim { get; set; } //To showcase what you get. + + private async Task OnReadHandler(GridReadEventArgs args) + { + string output = string.Empty; + + //Get the filtering and searching criteria. + output += "FILTERS:
"; + foreach (var item in args.Request.Filters) + { + if (item is CompositeFilterDescriptor) + { + CompositeFilterDescriptor currFilter = (CompositeFilterDescriptor)item; + output += $"START nested filter: Logical operator: {currFilter.LogicalOperator}, details:
"; + foreach (FilterDescriptor nestedFilter in currFilter.FilterDescriptors) + { + output += $"Filtered field: {nestedFilter.Member}, Filter operator: {nestedFilter.Operator}, Filter value: {nestedFilter.Value}
"; + } + output += "END nested filter
"; + } + } + + //Get the sorting criteria. + output += "SORTS:
"; + foreach (SortDescriptor item in args.Request.Sorts) + { + output += $"Sorted field: {item.Member}, Sort direction: {item.SortDirection}
"; + } + + //Get the grouping criteria. + output += "GROUPS:
"; + foreach (GroupDescriptor item in args.Request.Groups) + { + output += $"Grouped field: {item.Member}, Group sort direction: {item.SortDirection}
"; + } + + ConsoleSim = new MarkupString(output); + + var result = PristineData.ToDataSourceResult(args.Request); + + args.Data = result.Data; + args.Total = result.Total; + } + + private IEnumerable PristineData = Enumerable.Range(1, 300).Select(x => new SampleData + { + Id = x, + Name = "name " + x, + Team = "team " + x % 5, + HireDate = DateTime.Now.AddDays(-x).Date + }); + + public class SampleData + { + public int Id { get; set; } + public string Name { get; set; } + public string Team { get; set; } + public DateTime HireDate { get; set; } + } +} +```` + +## Example with Component State + +You can obtain the FilterDescriptor, SearchFilter, SortDescriptor, and GroupDescriptor through the component's state. + +````CSHTML +@using System.Text.Json +@using Telerik.DataSource + +

@ConsoleSim

+ + + + + + + + + + + + + +@code { + private MarkupString ConsoleSim { get; set; } + + private List GridData { get; set; } = new List(); + + private async Task OnGridStateChanged(GridStateEventArgs args) + { + string output = string.Empty; + + //Get the searching criteria. + output += "SEARCHING:
"; + var searching = args.GridState.SearchFilter; + + if (searching is CompositeFilterDescriptor) + { + CompositeFilterDescriptor currSearch = searching as CompositeFilterDescriptor; + output += $"START nested searching: Logical operator: {currSearch.LogicalOperator}, details:
"; + foreach (FilterDescriptor nestedSearch in currSearch.FilterDescriptors) + { + output += $"Search field: {nestedSearch.Member}, Search operator {nestedSearch.Operator}, Search value: {nestedSearch.Value}
"; + } + output += "END nested searching
"; + } + + + //Get the filtering criteria. + output += "FILTERS:
"; + + foreach (var item in args.GridState.FilterDescriptors) + { + if (item is CompositeFilterDescriptor) + { + CompositeFilterDescriptor currFilter = item as CompositeFilterDescriptor; + output += $"START nested filter: Logical operator: {currFilter.LogicalOperator}, details:
"; + foreach (FilterDescriptor nestedFilter in currFilter.FilterDescriptors) + { + output += $"Filtered field: {nestedFilter.Member}, Filter operator: {nestedFilter.Operator}, Filter value: {nestedFilter.Value}
"; + } + output += "END nested filter
"; + } + } + + //Get the sorting criteria. + output += "SORTS:
"; + foreach (SortDescriptor item in args.GridState.SortDescriptors) + { + output += $"Sorted field: {item.Member}, Sort direction: {item.SortDirection}
"; + } + + //Get the grouping criteria. + output += "GROUPS:
"; + foreach (SortDescriptor item in args.GridState.GroupDescriptors) + { + output += $"Grouped field: {item.Member}, Group sort direction: {item.SortDirection}
"; + } + + ConsoleSim = new MarkupString(output); + } + + protected override void OnInitialized() + { + var rnd = new Random(); + + for (int i = 1; i <= 12; i++) + { + GridData.Add(new Product() + { + Id = i, + Name = $"Product {i}", + Category = $"Category {i % 4 + 1}", + Stock = rnd.Next(0, 100), + Discontinued = i % 3 == 0 + }); + } + } + + public class Product + { + public int Id { get; set; } + public string Name { get; set; } = string.Empty; + public string Category { get; set; } = string.Empty; + public int Stock { get; set; } + public bool Discontinued { get; set; } + } +} +```` + +## See Also + +* [AutoComplete OnRead Event]({%slug autocomplete-events%}#onread) +* [ComboBox OnRead Event]({%slug components/combobox/events%}#onread) +* [DropDownList OnRead Event]({%slug components/dropdownlist/events%}#onread) +* [Filter Overview]({%slug filter-overview%}) +* [Gantt State]({%slug gantt-state%}) +* [Grid OnRead Event]({%slug components/grid/manual-operations%}) +* [Grid State]({%slug grid-state%}) +* [MultiColumnComboBox OnRead Event]({%slug multicolumncombobox-events%}#onread) +* [MultiSelect OnRead Event]({%slug multiselect-events%}#onread) +* [TreeList State]({%slug treelist-state%}) \ No newline at end of file diff --git a/common-features/filter-operators.md b/common-features/data-binding/filter-operators.md similarity index 99% rename from common-features/filter-operators.md rename to common-features/data-binding/filter-operators.md index 9f11202dcb..f4fe2c5989 100644 --- a/common-features/filter-operators.md +++ b/common-features/data-binding/filter-operators.md @@ -5,7 +5,7 @@ description: Supported Filter Operators in the Telerik UI for Blazor component s slug: common-features-filter-operators tags: telerik,blazor,filter,operator published: True -position: 10 +position: 15 --- # Filter Operators diff --git a/common-features/data-binding/observable-data.md b/common-features/data-binding/observable-data.md index 6ce4f6c924..c4360d11f9 100644 --- a/common-features/data-binding/observable-data.md +++ b/common-features/data-binding/observable-data.md @@ -6,7 +6,7 @@ slug: common-features-observable-data tags: telerik,blazor,observable,data,live,INotifyCollectionChanged published: True previous_url: /common-features/observable-data -position: 10 +position: 25 --- # Observable Data and Refresh Data diff --git a/common-features/telerik-datasource-package.md b/common-features/data-binding/telerik-datasource-package.md similarity index 99% rename from common-features/telerik-datasource-package.md rename to common-features/data-binding/telerik-datasource-package.md index 464fa087c4..355b225112 100644 --- a/common-features/telerik-datasource-package.md +++ b/common-features/data-binding/telerik-datasource-package.md @@ -5,7 +5,7 @@ description: Details about the Telerik.DataSource NuGet package that come with T slug: common-features-datasource-package tags: telerik,blazor,data,source,package published: True -position: 50 +position: 20 --- # Telerik DataSource Package diff --git a/components/autocomplete/events.md b/components/autocomplete/events.md index 80c568c5af..f30fb44820 100644 --- a/components/autocomplete/events.md +++ b/components/autocomplete/events.md @@ -116,14 +116,16 @@ from model: @Role ## OnRead -You can use the he [`OnRead` event]({%slug common-features-data-binding-onread%}) to provide data to the component according to some custom logic and according to the current user input and/or scroll position (for [virtualization]({%slug autocomplete-virtualization%})). The event fires when: +You can use the [`OnRead` event]({%slug common-features-data-binding-onread%}) to provide data to the component based on custom logic and the current user input and/or scroll position (when using [virtualization]({%slug autocomplete-virtualization%})). The event fires when: -* the component initializes -* the user [filters]({%slug autocomplete-filter%}) -* the user scrolls with [virtualization]({%slug autocomplete-virtualization%}) enabled +* The component initializes. +* The user [filters]({%slug autocomplete-filter%}). +* The user scrolls with [virtualization]({%slug autocomplete-virtualization%}) enabled. You can also call remote data through async operations. +Find out how to [get the applied filtering and grouping criteria]({%slug common-features-descriptors%}). + When using `OnRead`, make sure to set `TItem` and `TValue`. >caption Custom Data according to the user input in the AutoComplete diff --git a/components/autocomplete/filter.md b/components/autocomplete/filter.md index 8c1bd3abcd..bbe3ff22e2 100644 --- a/components/autocomplete/filter.md +++ b/components/autocomplete/filter.md @@ -12,7 +12,11 @@ position: 10 The AutoComplete component can filter the available suggestions, according to the current input. In this way users can find the desired value faster. To see the difference in behavior, visit the [Live Demo: AutoComplete Filtering](https://demos.telerik.com/blazor-ui/autocomplete/filtering) page. -To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. You can also implement custom (server) filtering and set a data source dynamically through the [`OnRead` event]({%slug autocomplete-events%}#onread). +To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. + +You can also use the [`OnRead` event]({%slug autocomplete-events%}#onread) to: +* Get the [applied filtering criteria]({%slug common-features-descriptors%}#through-the-onread-event). +* Implement custom (server) filtering and set data dynamically. ## Filter Operator diff --git a/components/combobox/events.md b/components/combobox/events.md index fd0f6b0990..c4ea813724 100644 --- a/components/combobox/events.md +++ b/components/combobox/events.md @@ -175,14 +175,16 @@ See the [ComboBox Overview - Selected Item]({%slug components/combobox/overview% ## OnRead -You can use the [`OnRead` event]({%slug common-features-data-binding-onread%}) to provide data to the component according to some custom logic and according to the current user input and/or scroll position (for [virtualization]({%slug combobox-virtualization%})). The event fires when: +You can use the [`OnRead` event]({%slug common-features-data-binding-onread%}) to provide data to the component based on custom logic and the current user input and/or scroll position (when using [virtualization]({%slug combobox-virtualization%})). The event fires when: -* the component initializes -* the user [filters]({%slug components/combobox/filter%}) -* the user scrolls with [virtualization]({%slug combobox-virtualization%}) enabled +* The component initializes. +* The user [filters]({%slug components/combobox/filter%}). +* The user scrolls with [virtualization]({%slug combobox-virtualization%}) enabled. You can also call remote data through `async` operations. +Find out how to [get the applied filtering and grouping criteria]({%slug common-features-descriptors%}). + When using `OnRead`, make sure to set `TItem` and `TValue`. >caption Custom Data according to the user input in the ComboBox diff --git a/components/combobox/filter.md b/components/combobox/filter.md index b9a08057e7..87c86fbb33 100644 --- a/components/combobox/filter.md +++ b/components/combobox/filter.md @@ -12,7 +12,11 @@ position: 10 The ComboBox component allows the user to filter the available items by their text, so they can find the one they need faster. -To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. You can also implement custom (server) filtering and set a data source dynamically through the [`OnRead` event]({%slug components/combobox/events%}#onread). +To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. + +You can also use the [`OnRead` event]({%slug components/combobox/events%}#onread) to: +* Get the [applied filtering criteria]({%slug common-features-descriptors%}#through-the-onread-event). +* Implement custom (server) filtering and set data dynamically. Filtering looks in the `TextField`, and the filter is reset when the dropdown closes. diff --git a/components/dropdownlist/events.md b/components/dropdownlist/events.md index 5b0f3c5477..2f39a00954 100644 --- a/components/dropdownlist/events.md +++ b/components/dropdownlist/events.md @@ -99,11 +99,13 @@ from the model: @MySelectedItem ## OnRead -You can use the [`OnRead` event]({%slug common-features-data-binding-onread%}) to provide data to the component according to some custom logic and according to the current user input and/or scroll position (for [virtualization]({%slug dropdownlist-virtualization%})). The event fires when: +You can use the [`OnRead` event]({%slug common-features-data-binding-onread%}) to provide data to the component based on custom logic and the current user input and/or scroll position (when using [virtualization]({%slug dropdownlist-virtualization%})). The event fires when: -* the component initializes -* the user [filters]({%slug components/dropdownlist/filter%}) -* the user scrolls with [virtualization]({%slug dropdownlist-virtualization%}) enabled +* The component initializes. +* The user [filters]({%slug components/dropdownlist/filter%}). +* The user scrolls with [virtualization]({%slug dropdownlist-virtualization%}) enabled. + +Find out how to [get the applied filtering and grouping criteria]({%slug common-features-descriptors%}). You can also call remote data through `async` operations. diff --git a/components/dropdownlist/filter.md b/components/dropdownlist/filter.md index e7f14f343e..210b97bdd5 100644 --- a/components/dropdownlist/filter.md +++ b/components/dropdownlist/filter.md @@ -12,7 +12,11 @@ position: 10 The DropDownList filter textbox allows users to filter the available items by their text and find the one they need faster. The filtering input is at the top of the dropdown popup. -To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. You can also implement custom (server) filtering and set a data source dynamically through the [`OnRead` event]({%slug components/dropdownlist/events%}#onread). +To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. + +You can also use the [`OnRead` event]({%slug components/dropdownlist/events%}#onread) to: +* Get the [applied filtering criteria]({%slug common-features-descriptors%}#through-the-onread-event). +* Implement custom (server) filtering and set data dynamically. Filtering looks in the `TextField`, and the filter is reset when the dropdown closes. diff --git a/components/filter/overview.md b/components/filter/overview.md index 6d6fcbcbb4..0b9e124cb1 100644 --- a/components/filter/overview.md +++ b/components/filter/overview.md @@ -63,7 +63,7 @@ The Blazor Filter provides parameters that allow you to configure the component: | Parameter | Type | Description | | ----------- | ----------- | ----------- | | `Class` | `string` | The class that will be rendered on the outermost element. | -| `Value` | `CompositeFilterDescriptor` | Sets the value of the filter component. | +| `Value` | [`CompositeFilterDescriptor`]({%slug common-features-descriptors%}#filtering) | Sets the value of the Filter component. | ## Filter Reference and Methods diff --git a/components/gantt/gantt-tree/filter/overview.md b/components/gantt/gantt-tree/filter/overview.md index 4030bd0c84..068927d143 100644 --- a/components/gantt/gantt-tree/filter/overview.md +++ b/components/gantt/gantt-tree/filter/overview.md @@ -26,19 +26,11 @@ You can filter more than one column at a time, and all filter rules will be appl ## Filter Descriptors -The Gantt filter state is stored in [CompositeFilterDescriptors](/blazor-ui/api/Telerik.DataSource.CompositeFilterDescriptor). The below information is important if you want to [get or change the Gantt filters programmatically]({%slug gantt-state%}). - -Each `CompositeFilterDescriptor` contains a [**collection** of `FilterDescriptor`s](/blazor-ui/api/Telerik.DataSource.FilterDescriptorCollection). All descriptors in the collection are applied with an *AND* or an *OR* `LogicalOperator`. - -* [Filter Row]({%slug gantt-filter-row%}) - each `CompositeFilterDescriptor` targets a specific field. By default, one filter can be applied to a field using the Filter Row operator. The filter value is stored in the first `FilterDescriptor` instance of the `CompositeFilterDescriptor` for that field. - -* [Filter Menu]({%slug gantt-filter-menu%}) - each `CompositeFilterDescriptor` targets a specific field. Filter values from the separate filter operators in the menu are stored in different `FilterDescriptor` instances of the dedicated `CompositeFilterDescriptor` for that field. - +You can get the applied filtering criteria for each filtered field. Use the [Gantt state]({%slug gantt-state%}) to obtain the user input, the filter operator and other filtering properties. Find out how in the [Data Operation Descriptors article]({%slug common-features-descriptors%}#filtering). ## Customize The Filter Editors -You can customize the editors rendered in the Gantt -by providing the `FilterEditorType` attribute, exposed on the ``. The `FilterEditorType` attribute accepts a member of the `GanttTreeListFilterEditorType` enum: +You can customize the editors rendered in the Gantt by providing the `FilterEditorType` attribute, exposed on the ``. The `FilterEditorType` attribute accepts a member of the `GanttTreeListFilterEditorType` enum: | Field data type | GanttTreeListFilterEditorType enum members | |-----------------|------------------------------------------| diff --git a/components/gantt/gantt-tree/sorting.md b/components/gantt/gantt-tree/sorting.md index 05618bfa47..c8fe9e8128 100644 --- a/components/gantt/gantt-tree/sorting.md +++ b/components/gantt/gantt-tree/sorting.md @@ -24,6 +24,8 @@ Sorting keeps the expanded/collapsed state of items. For example, if filtering b You can let the user sort by more than one field by setting the `SortMode` parameter to `Telerik.Blazor.SortMode.Multiple`. +The sorting criteria are stored in a [collection of `SortDescriptor`]({%slug common-features-descriptors%}#sorting). + >caption Enable Sorting in Telerik TreeList ````CSHTML diff --git a/components/gantt/state.md b/components/gantt/state.md index 0ac981fe1c..0d9f88bcf3 100644 --- a/components/gantt/state.md +++ b/components/gantt/state.md @@ -564,6 +564,8 @@ Sometimes you may want to know what the user changed in the Gantt (e.g., when th Find out what the user changed in the Gantt through the `PropertyName` of the `GanttStateEventArgs`. Override the user action by changing and then setting your desired state. +Find out how to [get the applied filtering and sorting criteria]({%slug common-features-descriptors%}). + >caption Know when the Gantt state changes, which parameter changes, and amend the change ````CSHTML diff --git a/components/grid/filter/overview.md b/components/grid/filter/overview.md index d736c8dd93..00eaa16965 100644 --- a/components/grid/filter/overview.md +++ b/components/grid/filter/overview.md @@ -37,16 +37,7 @@ The filter menu can display a [list of checkboxes]({%slug grid-checklist-filter% ## Filter Descriptors -The Grid filter state is stored in [`CompositeFilterDescriptors`](/blazor-ui/api/Telerik.DataSource.CompositeFilterDescriptor). Use the following information if you want to [get or change the Grid filters programmatically]({%slug grid-state%}). - -Each `CompositeFilterDescriptor` includes a collection of filter descriptors, where all descriptors in the collection are applied with an AND or OR logical operator. - -* [Filter Row]({%slug grid-filter-row%})—Each `CompositeFilterDescriptor` targets a specific field. By default, one filter can be applied to a field using the Filter Row operator, with the filter value stored in the first filter descriptor instance for that field. - -* [Filter Menu]({%slug grid-filter-menu%})—Each `CompositeFilterDescriptor` targets a specific field. The filter values from separate filter operators in the menu are stored in different filter descriptor instances within the `CompositeFilterDescriptor` for that field. - -* [SearchBox]({%slug grid-searchbox%})—A `CompositeFilterDescriptor` is created in the state when the user types in the search box. By default, it targets all string fields, adding a dedicated filter descriptor instance for each string field. Each filter descriptor contains the filter value typed in the search box. - +You can get the applied filtering criteria for each filtered field. Use the [Grid state]({%slug grid-state%}) or the [Grid `OnRead` event handler]({%slug grid-events%}#read-event) to obtain the user input, the filter operator and other filtering properties. Find out how in the [Data Operation Descriptors article]({%slug common-features-descriptors%}#filtering). ## Custom Filtering diff --git a/components/grid/state.md b/components/grid/state.md index 5ca4ab48f6..2787cc40a4 100644 --- a/components/grid/state.md +++ b/components/grid/state.md @@ -34,12 +34,12 @@ The Grid state is a generic [class `GridState`](/blazor-ui/api/Telerik.Bl | `EditField` | `string` | The currently edited data item property in [`Incell` edit mode]({%slug components/grid/editing/incell%}). | | `EditItem` | `TItem`* | The currently edited data item in [any edit mode]({%slug components/grid/editing/overview%}). | | `ExpandedItems` | `ICollection` | The expanded data items, when [using `` (hierarchy)]({%slug components/grid/features/hierarchy%}). | -| `FilterDescriptors` | `ICollection` | All filtering criteria, except the ones that relate to the[`GridSearchBox`]({%slug grid-searchbox%}). | +| `FilterDescriptors` | `ICollection` | A collection of [`CompositeFilterDescriptor`]({%slug common-features-descriptors%}#filtering), except the ones that relate to the [`GridSearchBox`]({%slug grid-searchbox%}). | | `GroupDescriptors` | `ICollection` | Information about currently applied [grouping]({%slug components/grid/features/grouping%}). | | `InsertedItem` | `TItem`* | The data item that is being added in `Inline` or `Popup` edit mode. [Not applicable for `Incell` editing]({%slug components/grid/editing/incell%}#event-sequence). | | `OriginalEditItem` | `TItem`* | The original copy of the data item that is currently in edit mode. This `GridState` property holds the unmodified data item values. | | `Page` | `int?` | The current [page index]({%slug components/grid/features/paging%}). Some user actions reset the page index to 1, such as filtering or changing the page size. | -| `SearchFilter` | `IFilterDescriptor` | The `CompositeFilterDescriptor` that holds the filter descriptors for the [`GridSearchBox`]({%slug grid-searchbox%}). | +| `SearchFilter` | `IFilterDescriptor` | The [`CompositeFilterDescriptor`]({%slug common-features-descriptors%}#filtering) that holds the filter descriptors for the [`GridSearchBox`]({%slug grid-searchbox%}). | | `SelectedItems` | `ICollection` | The currently [selected data item(s)]({%slug grid-selection-overview%}). | | `Skip` | `int?` | The number of scrolled data items when using [virtual row scrolling]({%slug components/grid/virtual-scrolling%}). In other words, this is the number of rows above the currently visible ones. | | `SortDescriptors` | `ICollection` | The currently applied [sorts]({%slug components/grid/features/sorting%}). | @@ -176,6 +176,8 @@ Here is some additional information about certain `PropertyName` values: To observe the changes in the Grid state more easily, copy and run the following example in a local app and at full screen. +Find out how to [get the applied filtering, sorting and grouping criteria]({%slug common-features-descriptors%}). + >caption Using Grid OnStateChanged ````CSHTML diff --git a/components/multicolumncombobox/events.md b/components/multicolumncombobox/events.md index d4ce2d75e3..171a7acbac 100644 --- a/components/multicolumncombobox/events.md +++ b/components/multicolumncombobox/events.md @@ -200,12 +200,14 @@ See the [MultiColumnComboBox Overview - Selected Item]({%slug multicolumncombobo You can use the `OnRead` event to provide data to the component according to some custom logic, the user input, or the current [virtual scroll]({%slug multicolumncombobox-virtualization%}) position. The event fires when: -* the component initializes -* the user [filters]({%slug multicolumncombobox-filter%}) -* the user scrolls with [virtualization]({%slug multicolumncombobox-virtualization%}) enabled +* The component initializes. +* The user [filters]({%slug multicolumncombobox-filter%}). +* The user scrolls with [virtualization]({%slug multicolumncombobox-virtualization%}) enabled. You can also call remote data through `async` operations. +Find out how to [get the applied by filtering and grouping criteria]({%slug common-features-descriptors%}). + When using `OnRead`, make sure to set `TItem` and `TValue`. >tip You can also [debounce the service calls and implement minimum filter length]({%slug combo-kb-debounce-onread%}). diff --git a/components/multicolumncombobox/filter.md b/components/multicolumncombobox/filter.md index e8af430eed..dedfa3260a 100644 --- a/components/multicolumncombobox/filter.md +++ b/components/multicolumncombobox/filter.md @@ -12,7 +12,11 @@ position: 10 The MultiColumnComboBox component allows users to filter items by their text, so they can find the one they need faster. -To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. You can also implement custom (server) filtering and set a data source dynamically through the [`OnRead` event]({%slug multicolumncombobox-events%}#onread). +To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. + +You can also use the [`OnRead` event]({%slug multicolumncombobox-events%}#onread) to: +* Get the [applied filtering criteria]({%slug common-features-descriptors%}#through-the-onread-event). +* Implement custom (server) filtering and set data dynamically. Filtering looks in the `TextField`, and the filter is reset when the dropdown closes. diff --git a/components/multiselect/events.md b/components/multiselect/events.md index 0f41ad264e..ab58a1ed50 100644 --- a/components/multiselect/events.md +++ b/components/multiselect/events.md @@ -98,12 +98,14 @@ from the model: You can use the he [`OnRead` event]({%slug common-features-data-binding-onread%}) to provide data to the component according to some custom logic and according to the current user input and/or scroll position (for [virtualization]({%slug multiselect-virtualization%})). The event fires when: -* the component initializes -* the user [filters]({%slug multiselect-filter%}) -* the user scrolls with [virtualization]({%slug dropdownlist-virtualization%}) enabled +* The component initializes. +* The user [filters]({%slug multiselect-filter%}). +* The user scrolls with [virtualization]({%slug dropdownlist-virtualization%}) enabled. You can also call remote data through async operations. +Find out how to [get the applied filtering and grouping criteria]({%slug common-features-descriptors%}). + >caption Custom Data according to the user input in the MultiSelect ````CSHTML diff --git a/components/multiselect/filter.md b/components/multiselect/filter.md index d0ecff0e2b..0cdd747b4b 100644 --- a/components/multiselect/filter.md +++ b/components/multiselect/filter.md @@ -12,7 +12,11 @@ position: 10 The MultiSelect component can filter the available suggestions according to the current user input, so they can find the one they need faster. To see the difference in behavior, visit the [Live Demo: MultiSelect Filtering](https://demos.telerik.com/blazor-ui/multiselect/filtering) page. -To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. You can also implement custom (server) filtering and set a data source dynamically through the [`OnRead` event]({%slug multiselect-events%}#onread). +To enable filtering, set the `Filterable` parameter to `true`. The filtering is case insensitive. + +You can also use the [`OnRead` event]({%slug multiselect-events%}#onread) to: +* Get the [applied filtering criteria]({%slug common-features-descriptors%}#through-the-onread-event). +* Implement custom (server) filtering and set data dynamically. Filtering looks in the `TextField`, and the filter is reset when the dropdown closes. diff --git a/components/treelist/filter/overview.md b/components/treelist/filter/overview.md index 92d8fbf75b..9d2f4f7713 100644 --- a/components/treelist/filter/overview.md +++ b/components/treelist/filter/overview.md @@ -44,15 +44,7 @@ In addition to the two main filtering modes, the treelist offers two more featur ## Filter Descriptors -The TreeList filter state is stored in [CompositeFilterDescriptors](/blazor-ui/api/Telerik.DataSource.CompositeFilterDescriptor). The below information is important if you want to [get or change the TreeList filters programmatically]({%slug treelist-state%}). - -Each `CompositeFilterDescriptor` contains a [**collection** of `FilterDescriptor`s](/blazor-ui/api/Telerik.DataSource.FilterDescriptorCollection). All descriptors in the collection are applied with an *AND* or an *OR* `LogicalOperator`. - -* [Filter Row]({%slug treelist-filter-row%}) - each `CompositeFilterDescriptor` targets a specific field. By default, one filter can be applied to a field using the Filter Row operator. The filter value is stored in the first `FilterDescriptor` instance of the `CompositeFilterDescriptor` for that field. - -* [Filter Menu]({%slug treelist-filter-menu%}) - each `CompositeFilterDescriptor` targets a specific field. Filter values from the separate filter operators in the menu are stored in different `FilterDescriptor` instances of the dedicated `CompositeFilterDescriptor` for that field. - -* [SearchBox]({%slug treelist-searchbox%}) - one `CompositeFilterDescriptor` is created in the state when the user types in the Searchbox. By default, it targets all `string` fields. A dedicated `FilterDescriptor` instance is added to this `CompositeFilterDescriptor` for each `string` field. Each `FilterDescriptor` instance contains the filter value typed in the Searchbox. +You can get the applied filtering criteria for each filtered field. Use the [TreeList state]({%slug treelist-state%}) to obtain the user input, the filter operator and other filtering properties. Find out how in the [Data Operation Descriptors article]({%slug common-features-descriptors%}#filtering). ## Customize The Filter Editors diff --git a/components/treelist/sorting.md b/components/treelist/sorting.md index 08f086ee05..464c38d332 100644 --- a/components/treelist/sorting.md +++ b/components/treelist/sorting.md @@ -24,6 +24,8 @@ Sorting keeps the expanded/collapsed state of items. For example, if filtering b You can let the user sort by more than one field by setting the `SortMode` parameter to `Telerik.Blazor.SortMode.Multiple`. +The sorting criteria are stored in a [collection of `SortDescriptor`]({%slug common-features-descriptors%}#sorting). + >caption Enable Sorting in Telerik TreeList ````CSHTML diff --git a/components/treelist/state.md b/components/treelist/state.md index d1d0c974aa..c8b78c52d5 100644 --- a/components/treelist/state.md +++ b/components/treelist/state.md @@ -537,6 +537,8 @@ Sometimes you may want to know what the user changed in the TreeList (e.g., when The example below shows how to achieve it by using the`OnStateChanged` event. +Find out how to [get the applied filtering and sorting criteria]({%slug common-features-descriptors%}). + >caption Know when the TreeList state changes, which parameter changed and amend the change ````CSHTML