Log In
[Expand]General Information
[Collapse]WinForms Controls
 [Expand]What's Installed
 [Expand]Build an Application
 [Expand]Controls and Libraries
 [Collapse]Common Features
  [Expand]Data Binding Common Concepts
  [Expand]Data Source Wizard
  [Expand]Application Appearance
  [Collapse]Filtering UI Context
   [Expand]Getting Started
   [Collapse]Advanced Concepts
     Base and Parent Filtering ViewModels
  [Expand]High DPI Support
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML Text Formatting
  [Expand]Tooltip Management
  [Expand]Saving and Restoring Layouts
   Clipboard - Copy Data and Formatting
   Version Compatibility: Default Property Values
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Report Server
[Expand]eXpressApp Framework
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Base and Parent Filtering ViewModels

Tutorials from the Getting Started section walk you through the standard 'WinForms way' of utilizing the Filtering UI Context. This includes five steps to generate the filtering UI:

  • create a class with public properties related to data fields that you wish to filter (for code-first data sources, you already have it);
  • add filtering attributes to these properties;
  • use the class you get as the Filtering UI Context component's filtering Model;
  • handle required filtering events to provide additional data for the filtering editors;
  • retrieve fields to populate the UI provider with editors (to do the same in code, call the component's RetrieveFields methods).

The diagram below illustrates this entire process.

The filtering ViewModel, displayed inside the Filtering UI Context on this diagram is automatically generated by the component itself and provides all business logic required to identify valid properties, parse filtering attributes and generate required editors. In this simplified approach, the filtering ViewModel always remains behind the scenes.

Another way of utilizing the Filtering UI Context is following the MVVM approach. This introduces a way to modify the filtering ViewModel - a core layer that provides all key Filtering UI Context functionality and is inaccessible when following the simplified scenario. The diagram below illustrates this advanced process.

Although in this scenario the Filtering UI Context still automatically generates its filtering ViewModel, you now can inherit this ViewModel from a desired custom class (base ViewModel) and/or relate it to another class using the parent-child relationship (parent ViewModel).

  • To inherit the automatically generated filtering ViewModel from a base ViewModel, use the component's smart-tag or set the BaseViewModelType property in code.
  • In order to use the desired class as a parent ViewModel, assign its instance to the ParentViewModel property or use the component's smart-tag. Alternatively, you can specify the ParentViewModelProvider property in order to use the same ViewModel as an existing MvvmContext component.

There is no specific recommendation on whether to use the base ViewModel only, the parent ViewModel, or both of them simultaneously. Use the approach that best fits your needs.

Expanded Replacing Filtering Events

As you notice in the diagram above, filtering events no longer take part in this MVVM-like approach, since handling events breaks the main MVVM concept of separating GUI from application logic. Instead, use filtering attributes, specifically, their parameters that end with '...Member'. The example below illustrates how to populate a look-up editor without handling the QueryLookupData event.

The CustomFilteringViewModel class uses the RetrieveCategoryList method to return a list containing all existing category names. This list with one additional custom item added to it is returned by the public ProductCategories property.

No matter whether you decide to use this class as a base or parent ViewModel, you can use its ProductCategories property to set the DataSourceMember parameter. Setting this parameter is identical to passing a lookup item collection to the e.Result.DataSource property of the QueryLookupData event handler. You can also specify the ValueMember and DisplayMember parameters to assign two additional base or parent ViewModel members. The first member will be used to build filter criteria objects while the second member returns values to be displayed to an end-user. Use these parameters when you have paired data fields like 'ModelName' and 'ModelID'.

The same applies to the remaining filtering events:

  • instead of handling the QueryRangeData event, add the FilterRange attribute and specify its MinimumMember , MaximumMember and AverageMember properties;
  • to replace the QueryBooleanChoiceData event, add the FilterBooleanChoice attribute and specify its DefaultValueMember paramter.

Expanded Metadata Classes

If your filtering Model changes (e.g., they will be re-generated when using code-first data sources), your filtering attributes declared in it will be lost. To avoid these issues, create a metadata class with public fields and all required filtering attributes. Then, with the help of the FilterMetadataType attribute, you can share these attributes with your filtering Model. See the 'Metadata Attributes' section of the Lesson 4 - Filtering Attributes article for an example.

How would you rate this topic?​​​​​​​