Custom Filtering

• Feb 02, 2023
• 6 minutes to read

The DevExpress MVC Combo Box (ComboBoxExtension) extension enables you to implement custom filtering logic on the server and client sides.

• Server-Side Functionality
• Client-Side Fucntionality

Server Side Functionality

Use the delegate specified by the AutoCompleteBoxBaseSettings.CustomFiltering property to filter editor items that fall within the filter criteria and highlight them on the server side.

Note

Note that if the ListEditCustomFilteringEventArgs.CustomHighlighting property is not in effect, and items are loaded on a callback during scrolling, this delegate 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) property to specify rules according to which the ComboBox highlights the filtered items. If the ListEditCustomFilteringEventArgs.CustomHighlighting property is not set, the AutoCompleteBoxBaseSettings.CustomFiltering property 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 instances of the “str” string in filtered items.

  C#

  e.CustomHighlighting = "str";
  

• Highlights all instances of the “str1” and “str2” strings in filtered items.

  Razor

  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.

  Razor

  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.

  Razor

  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 the filtered items.

  Razor

  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.

  Razor

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

Note

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

• The ASPxAutoCompleteBoxBase.IncrementalFilteringMode property is set to None.
• The ASPxAutoCompleteBoxBase.EnableCallbackMode property is set to false.

Online Demo

Refer to the ComboBox - Custom Filtering online demo to see this feature in action.

Example

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

Razor

@Html.DevExpress().ComboBox(settings => {
    settings.Properties.IncrementalFilteringMode = IncrementalFilteringMode.Contains;
    settings.Properties.Columns.Add(column => {
        column.FieldName = "CompanyName";
        column.Width = Unit.Pixel(250);
    });
    settings.Properties.Columns.Add(column => {
        column.FieldName = "Country";
        column.Width = Unit.Pixel(100);
    });
    settings.CustomFiltering += (s, e) => {
        string[] words = e.Filter.Split(new char[] { ' ' }, StringSplitOptions.RemoveEmptyEntries);
        string[] columns = new string[] { "CompanyName", "Country" };
        e.FilterExpression = GroupOperator.And(words.Select(w =>
            GroupOperator.Or(
                columns.Select(c =>
                    new FunctionOperator(FunctionOperatorType.Contains, new OperandProperty(c), w)
                )
            )
        )).ToString();
        e.CustomHighlighting = columns.ToDictionary(c => c, c => words);
    };
}).BindList(ViewData["Customers"]).GetHtml()

The result:

Client Side Functionality

Items Filtering

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

The ASPxClientListEditItemFilteringEventArgs.item property is used to access the processed item. To define the 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 the editor items that match the filter criteria. Note that the ComboBox 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 the 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 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.

  JS

  function onCustomHighlighting(s, e) {
      e.highlighting = e.filter;
  }
  

• Highlights all instances of the “Custom text” string among filtered items.

  JS

  function onCustomHighlighting(s, e) {
      e.highlighting = "Custom text";
  }
  

• Highlights all instances of the “str1” and “str2” strings among filtered items.

  JS

  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 the regular expression) among filtered items.

  JS

  function onCustomHighlighting(s, e) {
      e.highlighting = /text[a-c]/gi;
  }
  

• Highlights all instances of the “str1” string in the “Column1” and “str2” string in the “Column2” among filtered items.

  JS

  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.

  JS

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

Note

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

Example

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

JS

function onItemFiltering(s, e) {
    if (!e.isFit) {
        e.isFit = e.item.text.toLowerCase()
            .replace(/\u00fc/gi, "u")
            .replace(/\u00e4/gi, "a")
            .replace(/\u00f6/gi, "o")
            .indexOf(e.filter.toLowerCase()) > -1;
    }
}
function onCustomHighlighting(s, e) {
    e.highlighting = new RegExp(e.filter
        .replace(/u/gi, "(u|\u00fc)")
        .replace(/a/gi, "(a|\u00e4)")
        .replace(/o/gi, "(o|\u00f6)")
        , "gi");
}

Razor

Html.DevExpress().ComboBox(cmbSettings => {
...
    cmbSettings.Properties.ClientSideEvents.ItemFiltering = "onItemFiltering";
    cmbSettings.Properties.ClientSideEvents.CustomHighlighting = "onCustomHighlighting";
}).BindToXML(HttpContext.Current.Server.MapPath("~/App_Data/GermanCities.xml"), "//City").Render();

The result: