Custom Filtering

  • 6 minutes to read

The DevExpress ASP.NET Combo Box (ASPxComboBox) editor enables you to implement custom filtering logic on the server and client sides.

Server-Side Functionality

To filter editor items that fall within the filter criteria and highlight them on the server side, use the ASPxAutoCompleteBoxBase.CustomFiltering event.

NOTE

Note that if the ListEditCustomFilteringEventArgs.CustomHighlighting property is not in effect, and items are loaded on a callback during scrolling, this event is raised again.

Items Filtering

Use the ListEditCustomFilteringEventArgs.FilterExpression property to specify a filter expression based on the Criteria Operator syntax. If this property is not set, the "Contains/Starts with" comparison operator is used by default.

Items Highlighting

Use the ListEditCustomFilteringEventArgs.CustomHighlighting) to specify rules according to which the ASPxComboBox highlights filtered items. If the ListEditCustomFilteringEventArgs.CustomHighlighting property is not set, the ASPxAutoCompleteBoxBase.CustomFiltering event highlights the first occurrence of the search text typed in the editor's filtering area (regardless of the ListEditCustomFilteringEventArgs.FilterExpression property).

The ListEditCustomFilteringEventArgs.CustomHighlighting property can be specified in the following ways.

  • Highlights all "str" string instances in filtered items.

    
    e.CustomHighlighting = "str";
    
  • Highlights all "str1" and "str2" strings’ instances in filtered items.

    
    e.CustomHighlighting = new string[] { "str1", "str2" };
    
  • Highlights all instances of the "str1" string in the "Column1", and the "str2" string in the "Column2" among filtered items.

    
    e.CustomHighlighting = new Dictionary<string, string>() {
        { "Column1", "str1" },
        { "Column2", "str2" }
    };
    
  • Highlights all instances of the "str1" and "str2" strings in the "Column1", and the "str3" and "str4" strings in the "Column2" among filtered items.

    
    e.CustomHighlighting = new Dictionary<string, string[]>() {
        { "Column1", new string[] {"str1", "str2" } },
        { "Column2", new string[] { "str3", "str4" } }
    };
    

The following code snippets illustrate how to specify the ListEditCustomFilteringEventArgs.CustomHighlighting property using the regular expression. Set the ListEditCustomHighlighting.StringToRegularExpression property to true to convert the specified string into a regular expression on the client side. Otherwise, the editor will perceive this regular expression as a string.

NOTE

Note that the ListEditCustomFilteringEventArgs.CustomHighlighting property cannot be specified as a regular expression using an array of strings (string[]) and a Dictionary that contains an array of strings (Dictionary<string, string[]>).

  • Highlights the "text" string followed by one or more occurrences of the "a", "b" and "c" letters among filtered items.

    
    e.CustomHighlighting = "text[a-c]+";
    e.CustomHighlighting.StringToRegularExpression = true;
    
  • Highlights the "text" string followed by one or more occurrences of the "a", "b" and "c" letters in the "Column1", and the number "50" followed by digits between 0 and 9 in the "Column2" among filtered items.

    
    e.CustomHighlighting = new Dictionary<string, string>() { { "Column1", "text[a-c]+" }, { "Column2", "50[0-9]" } }
    e.CustomHighlighting.StringToRegularExpression = true;
    
NOTE

The ASPxAutoCompleteBoxBase.CustomFiltering event is not in effect in the following cases.

The ASPxAutoCompleteBoxBase.CustomFiltering event's ListEditCustomFilteringEventArgs.FilterExpression argument is not in effect if the combo box is in custom binding mode.

Example

The following example illustrates how to use the ASPxAutoCompleteBoxBase.CustomFiltering event to filter combo box items by several words through multiple columns.


<dx:ASPxComboBox ID="CmbCustomers" runat="server" Width="100%" DropDownWidth="550"
    DropDownStyle="DropDownList" DataSourceID="CustomersDataSource" ValueField="CustomerID"
    ValueType="System.String" TextFormatString="{0}" EnableCallbackMode="true" IncrementalFilteringMode="Contains"
    OnCustomFiltering="CmbCustomers_CustomFiltering">
    <Columns>
        <dx:ListBoxColumn FieldName="CompanyName" Width="100%" />
        <dx:ListBoxColumn FieldName="Country" Width="70px" />
    </Columns>
</dx:ASPxComboBox>

The result:

ASPxComboBox-CustomFilteringEvent

Client-Side Functionality

Items Filtering

Use the ASPxClientComboBox.ItemFiltering event to show or hide editor items in the search result. This event fires for each editor item during filtering.

The ASPxClientListEditItemFilteringEventArgs.item property is used to access processed item. To define processed item visibility in the search result, use the ASPxClientListEditItemFilteringEventArgs.isFit property. To get the search text entered by an end-user, use the ASPxClientListEditItemFilteringEventArgs.filter property.

NOTE

The ASPxClientComboBox.ItemFiltering event is not in effect if the ASPxAutoCompleteBoxBase.EnableCallbackMode property is set to true.

Items Highlighting

The ASPxClientComboBox.CustomHighlighting event enables you to highlight editor items that match the filter criteria. Note that the ASPxComboBox raises the ASPxClientComboBox.CustomHighlighting event once for all items, while it raises the ASPxClientComboBox.ItemFiltering event for each item.

NOTE

The ASPxClientComboBox.CustomHighlighting event can be raised either immediately after items are filtered (the ASPxAutoCompleteBoxBase.EnableCallbackMode property is set to false) or after the first callback is initiated (the ASPxAutoCompleteBoxBase.EnableCallbackMode property is set to true).

Use the ASPxClientListEditCustomHighlightingEventArgs.highlighting property to specify rules according to which the combo box highlights filtered items.

In callback mode, the ASPxClientListEditCustomHighlightingEventArgs.highlighting property's default value is obtained from the ListEditCustomFilteringEventArgs.CustomHighlighting property if the latter is specified in the ASPxAutoCompleteBoxBase.CustomFiltering event. If the callback mode is disabled or the ListEditCustomFilteringEventArgs.CustomHighlighting property is not specified, the ASPxClientListEditCustomHighlightingEventArgs.highlighting property’s default value is null.

The ASPxClientListEditCustomHighlightingEventArgs.highlighting property can be specified in the following ways.

  • Highlights all occurrences of the case-insensitive search text (the ASPxClientListEditCustomHighlightingEventArgs.filter property) in filtered items.

    
    function onCustomHighlighting(s, e) {
        e.highlighting = e.filter;
    }
    
  • Highlights all instances of the "Custom text" string among filtered items.

    
    function onCustomHighlighting(s, e) {
        e.highlighting = "Custom text";
    }
    
  • Highlights all the "str1" and "str2" strings’ instances among filtered items.

    
    function onCustomHighlighting(s, e) {
        e.highlighting = ["str1", "str2"];
    }
    
  • Highlights the "text" string followed by one or more occurrences of the "a", "b" and "c" letters (specified by a regular expression) among filtered items.

    
    function onCustomHighlighting(s, e) {
        e.highlighting = /text[a-c]/gi;
    }
    
  • Highlights all "str1" string instances in the "Column1" and "str2" strings in the "Column2" among filtered items.

    
    function onCustomHighlighting(s, e) {
        e.highlighting = { "Column1": "str1", "Column2": "str2" };
    }
    
  • Highlights all instances of the "str1" and "str2" in the "Column1" and the "text" string followed by one or more occurrences of the "a", "b" and "c" letters in the "Column2" (specified by the regular expression) among filtered items.

    
    function onCustomHighlighting(s, e) {
        e.highlighting = { "Column1": ["str1", "str2"], "Column2": new RegEx("text[a-c]+", "gi") } ;
    }
    
NOTE

Setting the ASPxClientListEditCustomHighlightingEventArgs.highlighting disables default highlighting that is based on the TextFormatString property.

Online Demo

ASPxComboBox - Custom Filtering

Example

The following example illustrates how to use the ASPxClientComboBox.CustomHighlighting event to filter combo box items that contain diacritic characters.


<dx:ASPxComboBox ID="CmbWithClientFiltering" runat="server" Width="100%" DropDownWidth="550"
DropDownStyle="DropDownList" ValueField="Name" TextField="Name" DataSourceID="GermanCitiesDataSource" IncrementalFilteringMode="Contains">
    <ClientSideEvents ItemFiltering="onItemFiltering" CustomHighlighting="onCustomHighlighting" />
</dx:ASPxComboBox>

The result:

ASPxComboBox-ItemFilteringEvent