The requested page is not available for the requested platform. You are viewing the content for Default platform.

Header Filter

  • 5 min to read

End users can click a column header button to invoke a drop-down window with filter controls. The drop-down window's appearance and functionality depend on the column type and grid settings. Refer to the “Header Filter Modes” section for a list of available UIs.
The following properties specify the filter button's availability:

Property Description
ASPxGridSettings.ShowHeaderFilterButton Shows or hides filter buttons for all columns in the grid control.
GridDataColumnSettings.AllowHeaderFilter Specifies whether a filter button is available in a column.

If a filter is applied to a column, other column header filters display the sorted rows' unique values. To show the full list of values (including hidden rows' values), hold down SHIFT and click a header filter button.

The Header filter supports keyboard navigation if the control's ASPxGridBase.AccessibilityCompliant property is enabled. You can use Tab to focus the filter button and press Enter to open a header filter popup window. Use Up and Down arrows to navigate the list of filter items, or Tab if the GridDataColumnHeaderFilterSettings.Mode property is set to CheckedList. To close the header filter popup window and apply the filter criteria, use Enter. Press Esc to close the popup window without saving changes.

Header Filter Modes

You can use a column's GridDataColumnHeaderFilterSettings.Mode property to specify its filter mode.

The following list modes are available for all grid columns:

  • List. The header filter is displayed as a regular list of filter items. Clicking an item invokes the corresponding action and automatically closes the drop-down list.

    HeaderFilter_List

  • CheckedList. The header filter is displayed as a checked list of filter items. In this mode, an end user can select multiple items simultaneously. When you click OK to close the drop-down window, the grid displays the records that contain checked values.

    HeaderFilter_CheckList1

The following list modes are available for date columns only:

Note

Refer to the Criteria Language Syntax and FunctionOperatorType topics that describe how to compose complex filter criteria using function operators.

Custom Header Filter Items

The ASPxGridView allows you to create custom filter values, define their filter criteria, and display these values within a column's drop-down filter. To do this, handle the ASPxGridView.HeaderFilterFillItems event. You can use the ASPxGridHeaderFilterEventArgs.Values event parameter to access the default filter values. To add a new filter item, use the ASPxGridHeaderFilterEventArgs.AddValue method. In the List mode, you can use the ASPxGridHeaderFilterEventArgs.AddShowAll method to add a ShowAll button to the list.

The FilterValue.CreateShowAllValue, FilterValue.CreateShowBlanksValue, and FilterValue.CreateShowNonBlanksValue methods can be used to create the corresponding filter items.

This example shows how to create custom filter items and display them within the Units On Order column's filter dropdown.

The image below shows the result:

HeaderFilterFillItems

protected void ASPxGridView1_HeaderFilterFillItems(object sender, DevExpress.Web.ASPxGridViewHeaderFilterEventArgs e) {
     if (e.Column.FieldName != "UnitsOnOrder") return;
     e.AddValue("nonzero", string.Empty, "[UnitsOnOrder] != 0");
     e.AddValue(String.Format("from {0} to {1}", 0, 50), string.Empty, String.Format("[UnitsOnOrder] > {0} and [UnitsOnOrder] < {1}", 0, 50));
     e.AddValue(String.Format(">= {0}", 50), string.Empty, String.Format("[UnitsOnOrder] >= {0}", 50));
}

Using HTML tags in an item text

The ASPxGridView header filter allows you to use HTML tags in an item text. This example demonstrates how you can set numbers in bold by using HTML tags within an item's format pattern. The image below shows the result.

ASPxGridView_HtmlTags

protected void grid_HeaderFilterFillItems(object sender, ASPxGridViewHeaderFilterEventArgs e) {
     if(e.Column.FieldName == "Quantity")
          PrepareQuantityFilterItems(e);
     ...
}

protected virtual void PrepareQuantityFilterItems(ASPxGridViewHeaderFilterEventArgs e) {
     int max = 0;
     for(int i = 0; i < e.Values.Count; i++) {
          int value;
          if(!int.TryParse(e.Values[i].Value, out value)) continue;
          if(value > max) max = value;
     }
     e.Values.Clear();
     int step = 10;
     for(int i = 0; i < max / step + 1; i++) {
          int start = step * i;
          int end = start + step - 1;
          e.AddValue(string.Format("from <b>{0}</b> to <b>{1}</b>", start, end), "", string.Format("[Quantity] >= {0} and [Quantity] <= {1}", start, end));
     }   
}