Log In
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Collapse]eXpressApp Framework
 [Expand]Getting Started
 [Expand]Design-Time Features
 [Collapse]Task-Based Help
  [Expand]Business Model Design
  [Expand]Application Model
  [Expand]List Editors
  [Expand]Property Editors
    How to: Filter a Link Dialog's List View
    How to: Filter Large List Views using the Auto Filter Row
    How to: Filter List Views on the UI Specific Level
    How to: Implement Cascading Filtering for Lookup List Views
    How to: Use Function Criteria Operators to Filter List Views
  [Expand]Scheduler and Notifications
  [Expand]Miscellaneous UI Customizations
  Frequently Asked Questions (FAQ)
 [Expand]API Reference
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
This documentation page describes implementations made in our v17.2 release cycle. To learn about functionality shipping with v18.1, navigate to our updated help file experience at docs.devexpress.com. Learn More

How to: Implement Cascading Filtering for Lookup List Views

Most applications have Detail Views which contain Lookup Property Editors that need to be filtered. Often, you should make the List View data source of these editors dependent on values of other Property Editors located in the same Detail View. For this purpose, the eXpressApp Framework provides the DataSourcePropertyAttribute and DataSourceCriteriaAttribute. This topic demonstrates how to use both these attributes in code and using the Application Model. In these examples, the Order, Product and Accessory classes will be implemented in different ways.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E218.

Expanded Initial Implementation

Initially, an Order includes a Product and Accessory. In addition, each Accessory is related to a particular Product. So, the Product and Accessory objects are related by a One-to-Many relationship. The following code shows how these classes can be implemented:

The image below demonstrates the Order Detail View in a Windows Forms application:

Here, the Product and Accessory Lookup Property Editors provide the entire Product and Accessory objects collections. However, certain scenarios may require a filtered collection to be displayed within the Accessory Lookup Property Editor.

Expanded Scenario 1 - Populate the Lookup with Objects from the Specified Collection Property

In the Order Detail View, it would be convenient if the Accessory Lookup Property Editor only provided the Accessory objects related to the currently selected Product. To accomplish this, the DataSourcePropertyAttribute attribute can be used. This attribute's value specifies a property whose possible values serve as the data source for the current lookup property. For the Order class' Accessory property, this attribute should be set to the Product class' Accessory property:

The following image demonstrates the resulting Order Detail View:

The same result can be achieved if you specify the DataSourceProperty property of the Application Model's Application | BOModel | Class | Member node.


  • An independent server-mode collection is created as a data source for a lookup ListView when the IModelListView.DataAccessMode option is set to Server or InstantFeedback for that ListView model. However, when the DataSourcePropertyAttribute is applied for the lookup property, the property pointed in the attribute is used as a lookup data source, and the standalone independent server-mode collection is not created and is not used at all. The reason is that the data source property getter contains logic calculated on the client side and the data source is populated by the client application at the moment when the lookup editor requests to display objects. So, the Server or InstantFeedback mode option and the DataSourceProperty attribute do not work simultaneously.
  • To use the approach demonstrated above for Entity Framework objects with a many-to-many relationship implemented through an intermediate object, use the Map method to specify the join table, its columns names, and to apply additional configuration. To learn more, refer to the Entity Framework Fluent API - Relationships topic.

Expanded Scenario 2 - Apply Criteria For the Lookup Property Collection

It may be necessary for a Lookup List View to contain objects whose properties satisfy a specified criteria. For example, there can be Accessories that can be chosen for every Product, so called Global Accessories. To display these Global Accessories in the Order Detail View, the DataSourceCriteriaAttribute attribute can be used. This attribute's value specifies the required criteria:

The same result can be achieved if you specify the DataSourceCriteria property of the Application Model's BOModel | Class | Member node.

Expanded Scenario 3 - Use Alternate Criteria if the Specified Data Source Property is Empty

Let a Lookup Property data source depend on a value of another property (see Scenario1). When this value is not specified, you can provide another data source. For example, when a Product is not specified in the Product Lookup Property Editor of the Order Detail View, the Accessories Lookup Property Editor will provide the collection of Global Accessories. To accomplish this, the DataSourcePropertyIsNullMode and DataSourcePropertyIsNullCriteria parameters can be specified for the DataSourceProperty attribute.


In addition to the CustomCriteria value, the DataSourcePropertyIsNullMode parameter of the DataSourceProperty attribute can also have the SelectAll and SelectNothing values. In this instance, you do not need to specify the DataSourcePropertyIsNullCriteria parameter.

The same result can be achieved if you specify the DataSourceProperty, DataSourcePropertyIsNullMode and DataSourcePropertyIsNullCriteria properties of the Application Model's BOModel | Class | Member node.

Expanded Scenario 4 - Populate the Lookup Manually

Assume the Accessory Lookup Property data source can contain Global Accessories (see Scenario 2) in addition to the currently selected Product's Accessories (see Scenario 1). In addition, assume there is a flag called IncludeGlobalAccessories. If it is in effect, the Accessory Lookup Property data source is composed of both the current Product's Accessories and Global Accessories. Otherwise, it is made up of the current Product's Accessories only. For this purpose, an additional collection must be shown for the Accessory property. This collection must be refreshed each time the Product or IncludeGlobalAccessories property is changed. The following code demonstrates how to implement the Order class for this task.

This approach cannot be implemented in a Mobile application, because the Mobile platform does not support non-persistent Collection Properties.

The following image shows an Order Detail View:


This approach to filter Lookup List Views is helpful when you cannot write the required criteria as a string to pass it as an attribute's parameter. In code, you can use any criteria operator and any operands (including Function Criteria Operators).

Expanded Scenario 5 - Filter the Lookup Property Collection Based on the Current Object's Properties

To access the currently edited record in criteria passed to the DataSourcePropertyAttribute, use the Current Object Parameter (@This). With the code below, the Contact.Manager lookup will display all Contacts with the "Manager" Position except for the current Contact.


This code snippet is not included in the linked How to Filter Lookup List Views example. Instead, it is demonstrated in the %PUBLIC%\Documents\DevExpress Demos 18.1\Components\eXpressApp Framework\MainDemo\CS\MainDemo.Module\BusinessObjects\Contact.cs file of Main Demo solution shipped with XAF. You can also see a similar code in the Implement Dependent Reference Properties (XPO) tutorial.

Expanded See Also

Is this topic helpful?​​​​​​​