Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Collapse]Editors and Simple Controls
   [Expand]Simple Editors
   [Collapse]Lookup Editors
     Lookup Editors and Main Settings
     Standard Binding (to Simple Data Types)
     Advanced Binding (to Business Objects)
     Using a Dictionary Lookup Data Source
     Combobox Mode - Allow Entering New Values
     Cascading Lookups
   [Expand]Token Edit Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  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

Cascading Lookups

In standalone mode, a lookup editor supports automatic filtration of its popup data source based on a value of another lookup editor. This topic shows how to customize lookup editors to perform this task.

Automatic filtration of popup data sources is supported for the LookUpEdit, GridLookUpEdit and SearchLookUpEdit controls in standalone mode. In in-place mode, data source filtration needs to be performed manually, as demonstrated in the How to: Filter a LookUp(ComboBox) Column Based on Another Column Value example.

Assume that two lookup editors display lists of Categories and Products in their dropdowns, respectively. Each Product corresponds to a certain Category. When an end-user selects a Category in the first lookup editor, the second editor's popup data source needs to be filtered to show only products that correspond to the selected category.

To link the secondary lookup editor to the primary lookup editor, the following properties on the secondary lookup editor are used.

  • LookUpEditBase.CascadingOwner - Specifies the primary lookup editor, whose value changes are tracked by the secondary lookup editor. Once a value change is detected, corresponding filter criteria are created and applied to the secondary popup data source. The filter criteria are created in the form:

    ForeignKeyField='Value'

    where the ForeignKeyField is a key field that uniquely identifies a record in the primary lookup data source.

    In case of multiple key fields in the primary lookup data source, the filter criteria are formed as follows.

    ForeignKeyField1='Value' AND ForeignKeyField2='Value2'...

  • RepositoryItemLookUpEditBase.CascadingMember (can be omitted in some cases) - Allows you to manually specify the ForeignKeyField(s) for the filter criteria applied to the secondary popup data source. In most cases, there is no need to specify the CascadingMember property, as the lookup editor provides an internal algorithm that identifies the ForeignKeyField(s) based on names of business objects, data types of primary keys, certain methods provided by lookup data sources (when the data source is a typed DataTable), key attributes, and other logic. The algorithm relies on the naming convention of key fields using the "ID", "Key" and "OID" strings/suffixes.

    Here is the general description of how the foreign key identification works when lookup data sources are collections of business objects (the algorithm may be changed in future versions). When identifying a subset of potential foreign keys, the lookup editor first excludes the primary key on the secondary lookup data source from this subset. Primary keys are typically named "ID", "Key" or "OID", or they have the "ID", "Key" or "OID" suffix. You can manually mark your primary key field on the secondary lookup data source with a dedicated key attribute (e.g., System.ComponentModel.DataAnnotations.KeyAttribute). This unambiguously identifies the primary key field and prevents a foreign key from being considered a primary key.

    The name of objects in the primary data source is concatenated with the "ID", "Key" and "OID" suffixes. The result of concatenation is compared with field names in the secondary lookup data source. If a match is found, this found field's data type is compared with the data type of the primary key field in the primary data source. If the found field satisfies all requirements, it is considered a foreign key and is used to build the filter criteria.

    If the internal algorithm is not able to identify a foreign key, manually assign this key to the CascadingMember property. In case of multiple foreign keys, set the CascadingMember property to a string that concatenates foreign key names by delimiting them with the ';' character.

    You can customize the filter criteria applied to the LookUpEdit control's popup data source by handling the RepositoryItemLookUpEdit.PopupFilter event. For GridLookUpEdit and SearchLookUpEdit, you can customize the filter by handling the ColumnView.SubstituteFilter event for a ColumnView object stored in the RepositoryItemGridLookUpEditBase.View property.

Expanded Example

Show Me

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

This example shows how to filter the popup data source of a standalone LookUpEdit control based on the value of another standalone LookUpEdit control.

The example demonstrates the automatic filtration feature supported by the LookUpEditBase.CascadingOwner property.

In the example, data sources of two lookup editors are lists of Category and Product business objects, respectively. When an end-user selects a certain category in the first lookup editor, the second lookup editor's popup should display those products that correspond to the selected category.

For the second lookup editor, the LookUpEditBase.CascadingOwner property is set to the first lookup editor. This specifies that the editor builds filter criteria based on the first lookup editor's value.

The filter criteria applied to the second data source is created in the form:

ForeignKeyField='Value'

The lookup editor's built-in algorithm identifies the "CategoryID" field as the foreign key for the filter criteria. The algorithm identifies the primary key field ("Key") for the first business object (this field's data type is taken into account for further analysis). The algorithm also obtains the first business object name ("Category") and concatenates it with the "ID", "Key" and "OID" suffixes. The "Category"+"ID" combination produces a valid property name in the second data source ("CategoryID"). In addition, the types of the "CategoryID" and "Key" fields match. Thus "CategoryID" is regarded as a foreign key field.
Note

The algorithm may be changed in future versions.

Note

If the built-in algorithm is not able to find a foreign key(s) in your own projects, you can manually specify the foreign key(s) with the RepositoryItemLookUpEditBase.CascadingMember property.

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