Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [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]Expressions
  [Expand]Behaviors
  [Expand]Application Appearance
  [Collapse]Filtering UI Context
   [Collapse]Getting Started
     Lesson 1 - Initial Setup
     Lesson 2 - Generating Editors. Filtering Model
     Lesson 3 - Filtering Events
     Filtering UI Context Designer
     Lesson 4 - Filtering Attributes
   [Expand]Advanced Concepts
  [Expand]High DPI Support
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML Text Formatting
  [Expand]Menus
  [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]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Lesson 4 - Filtering Attributes

The Filtering UI Context component can recognize attributes declared before filtering Model properties. These attributes affect the filtering editors' appearance and behaviors. There are two types of supported attributes.

Note

If you declare filtering attributes after clicking the 'Retrieve Fields' link (see Lesson 2 - Generating Editors. Filtering Model), you will probably need to remove all previously generated editors and retrieve them again in order to see these attributes work.

Tip

You can use filtering attributes outside the scope of the Filtering UI Context component. For instance, by utilizing these attributes you can select what editors appear inside an Excel-style filter.

Expanded FilterBooleanChoice

This attribute is used to mark boolean properties and provides the following members.

  • EditorType - allows you to choose which editor will be generated for this boolean property:
    • Check Edit (default)
    • ComboBox Edit
    • Radio Group
    • Toggle Switch Edit
  • DefaultName, TrueName, FalseName - replace default 'True', 'False' and 'Default' options' names for ComboBox Edit and Radio Group editors.
  • DefaultValue - specifies a boolean value, filtering by which should be ignored. The same is true for the QueryBooleanChoiceData event.
  • DefaultValueMember - similar to the DefaultValue property, but instead of specifying the irrelevant boolean value explicitly, you refer to a property or a method that returns this value. This member must be declared in either a base or parent ViewModel.
The code sample below illustrates how to use this attribute.

The figure below illustrates the result.

Expanded FilterRange

Declare this attribute before a numeric property to change the editor type and provide frontier editor values.

  • EditorType - for filtering numeric properties you can use:
    • two Text Edits (default)
    • two Spin Edits
    • Range Trackbar
  • FromName, ToName - replace default 'From' and 'To' captions next to Text or Spin Edit editors.
  • Minimum, Maximum, Average - set frontier values for the numeric property. Identical to the QueryRangeData event.
  • MinimumMember, MaximumMember, AverageMember - allow you to implement a more flexible behavior, where minimum, maximum and average values are set not explicitly, but rather returned by specific members declared in either a base or parent ViewModel.

Expanded FilterDateTimeRange

An attribute that manages editors, used for filtering DateTime properties.

  • EditorType - allows you to choose from multiple editor variations. Currently, only the Default/Range value is operational. This value allows you to display two DateEdit editors.
  • Since this attribute derives from the same base class as the FilterRange attribute, it exposes the same properties: FromName, Minimum, AverageMember, etc.

Expanded FilterEnumChoice

This attribute allows you to customize editors for properties that store enumeration values. Alternatively, it makes it possible to treat non-enumeration properties as if they were of the Enum type. For example, the sample filtering Model from Lesson 2 contains the Doors property. This is an integer property and thus, the Filtering UI Context by default generates 'From' and 'To' text boxes. Not only does filtering cars by the setting door number range look weird and irrational, but this property also has a very limited number of possible values. Having said that, you can treat this property as an enumeration where end-users can choose one specific value instead of setting a value range.

To do so, create your own custom enumeration and declare the EnumDataType attribute before the Doors property (see the code sample below). By doing so, you map integer property values to corresponding enumeration constant names. The property will now be recognized as an enumeration-typed property by the Filtering UI Context and you will be able to use the FilterEnumChoice attribute to customize the generated editor. Note that enumeration values can be marked with the Display attribute in order to change their display names.

The result is shown below.

The FilterEnumChoice attribute provides the following properties.

  • EditorType - allows you to choose which editor should be generated for the current filtering Model property.
  • UseSelectAll - gets or sets whether or not the editor should display the item that chooses all available options. The SelectAllName property allows you to replace this item's caption.

Expanded FilterLookup

An attribute that marks complex properties (string, Object, etc.) that have an unlimited amount of possible values. Provides the capability to load and/or initially display a specific item number.

  • EditorType - supports the following editors:
  • DataSourceMember - refers to a member that returns a collection of lookup items for this editor. This member must be declared in either the base or parent ViewModel.
  • Top, MaxCount - allow you to limit the number of initially visible items and their overall amount. See the QueryLookupData event to learn more.
  • TopMember, MaxCountMember - the same as before, but accept the names of either base or parent ViewModel members that return the required numbers, instead of specifying these numbers manually.
  • UseSelectAll, SelectAllName - the same as for the FilterEnumChoice attribute.

Expanded Metadata Attributes

The example attached to the Data Annotation Attributes topic illustrates how to use the Microsoft's MetadataType attribute to inherit attributes declared within a separate class. The same attribute is supported by the Filtering UI Context. Additionally, DevExpress provides the FilterMetadataType attribute that has priority over the MetadataType attribute and is designed to specifically inherit filtering attributes. Both attributes must be declared before the filtering Model's class declaration.

The following code displays the filtering Model that uses only standard attributes to customize the editor appearance. All filtering attributes are declared in a separate class and inherited by the filtering Model marked with the FilterMetadataType attribute. Note that you do not need to completely duplicate filtering Model properties within your metadata class. Declaring object-typed public fields is sufficient.

Similar to what is described in the Meta-POCO Bindings section of the Data Bindings and Notifications topic, you can use the MetadataBuilder to build all required metadata using the Fluent API. The code below illustrates an example.

After your metadata class is ready, you need to register it. The code below demonstrates how to register the sample metadata class and set up a relationship between it and the filtering Model .

Important

Using the metadata builder requires the DevExpress.MVVM library to be referenced by your application.

Expanded Data Annotation Attributes

These are standard Microsoft attributes, declared in the System.ComponentModel.DataAnnotations namespace. Using these attributes you can do the following.

  • Change the caption of a generated filtering editor (if it has any) and place it to a specific group. To do so, use the Name and GroupName parameters of the Display attribute.
  • Prohibit generating editors for certain filtering Model properties. This feature is very useful for using code-first data sources, where your data class can be used directly as a filtering Model. Such classes often contain properties for data fields that should not be available for filtering (e.g., product IDs). To disable filtering by such properties, set the AutoGenerateFilter parameter of the Display attribute to false.
  • Format editors data by using the DataType and DisplayFormat attributes. The code sample below illustrates how to format data within the 'Price' property' editors as currency.
To learn more about data annotation attributes, refer to the Using Data Annotations to Customize Data Classes MSDN topic.

Expanded See Also

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