Search Panel

• Jun 12, 2023
• 6 minutes to read

The Search Panel allows end-users to locate data by typing the filter criterion in the panel editor and highlight the search results.

Set the ASPxGridSearchPanelSettings.Visible property to true to enable the search panel. The ASPxGridView.SettingsSearchPanel property allows you to access the panel settings.

A search panel filter criterion is automatically applied after a certain time period (ASPxGridSearchPanelSettings.Delay) by default. Set the ASPxGridSearchPanelSettings.AllowTextInputTimer property to false to disable this time delay. In this case, the filter criterion is not automatically applied. An end-user can click the Apply (Search) button or press the ENTER key to apply the entered criterion.

Note

Search Panel Limitations * Search results contained in templates are not highlighted automatically. However, you can implement the highlighting manually.

• The search panel highlighting may break the current HTML structure when grid view text contains HTML tags and the EncodeHtml property is set to false.

  According to the searching logic, the Grid View obtains all the text from a database field, determines matches and wraps all matches in a span element to highlight them. When the EncodeHtml property is set to false, this logic may break the current HTML structure. You can either disable ASPxGridSearchPanelSettings.HighlightResults or define a GridViewDataColumn.DataItemTemplate for this column to prevent highlighting if an entered text contains HTML parts.

How to apply a search panel filter in code

You can apply a search panel filter in code on the server and client side.

On the server side

The code sample below demonstrates how to specify the search panel filter in code on the server side using the ASPxGridBase.SearchPanelFilter property.

Razor

@Html.DevExpress().GridView(settings => {
    settings.Name = "gridView";
    settings.SettingsSearchPanel.Visible = true;
...
}).Bind(Model).GetHtml()

On the client side

The code sample below demonstrates how to specify the search panel filter in code on the client side using the ASPxClientGridView.ApplySearchPanelFilter method.

Razor

@Html.DevExpress().GridView(settings => {
    settings.Name = "gridView";
    settings.ClientInstanceName = "grid";
    settings.SettingsSearchPanel.Visible = true;
...
}).Bind(Model).GetHtml()

JS

grid.ApplySearchPanelFilter('big');

Note

The ASPxGridBase.SearchPanelFilter property and ASPxClientGridView.ApplySearchPanelFilter method are in effect even if the search panel is disabled (the ASPxGridSearchPanelSettings.Visible property is set to false).

How to specify the columns to which the search panel filter is applied

The search panel filter is applied to all visible data columns in the grid view.

Use the ASPxGridViewSearchPanelSettings.ColumnNames property to apply the filter to particular columns. The property lists column identifiers that can be either a column name (WebColumnBase.Name), field name (GridViewDataColumn.FieldName), or caption(WebColumnBase.Caption).

Razor

@Html.DevExpress().GridView(settings => {
    settings.Name = "gridView";
    settings.SettingsSearchPanel.Visible = true;
    settings.SettingsSearchPanel.ShowApplyButton = true;
    settings.SettingsSearchPanel.ShowClearButton = true;
    settings.SettingsSearchPanel.ColumnNames = "ContactName; CompanyName";
...
}).Bind(Model).GetHtml()

To exclude a particular column from filtering, set the column’s GridDataColumnSettings.AllowFilterBySearchPanel property to false.

Razor

@Html.DevExpress().GridView(settings => {
    settings.Name = "gridView";
    settings.SettingsSearchPanel.Visible = true;
    settings.SettingsSearchPanel.ShowApplyButton = true;
    settings.SettingsSearchPanel.ShowClearButton = true;

    settings.Columns.Add("ContactName");
    settings.Columns.Add(i => {
        i.FieldName = "CompanyName";
        i.Settings.AllowFilterBySearchPanel = DefaultBoolean.False;
    });
    settings.Columns.Add("Address");
    settings.Columns.Add("City");
    settings.Columns.Add("PostalCode");
    settings.Columns.Add("Country");
    settings.Columns.Add("Phone");
...
}).Bind(Model).GetHtml()

How to change the default search panel editor with a custom one

The GridView extension allows you to replace a default editor with another DevExpress editor using the GridViewSettings.SearchPanelEditorCreate property.

Razor

@Html.DevExpress().GridView(settings => {
    settings.Name = "gridView";
    settings.SettingsSearchPanel.Visible = true;
    settings.SettingsSearchPanel.ShowApplyButton = true;
    settings.SettingsSearchPanel.ShowClearButton = true;

    settings.SearchPanelEditorCreate = (sender, e) => {        
        e.EditorProperties = new SpinEditProperties();
    };
...
}).Bind(Model).GetHtml()

Alternatively, specify an external DevExpress editor with the ASPxGridSearchPanelSettings.CustomEditorID property.

Razor

@Html.DevExpress().GridView(settings => {
    settings.Name = "gridView";
    settings.SettingsSearchPanel.Visible = true;
    settings.SettingsSearchPanel.ShowApplyButton = true;
    settings.SettingsSearchPanel.ShowClearButton = true;
    settings.SettingsSearchPanel.CustomEditorID = "TestBox1";
...
}).Bind(Model).GetHtml()
...
@Html.DevExpress().TextBox(settings => {
    settings.ID = "TextBox1";
    settings.Width = 170;
...
}).Bind(Model).GetHtml()

Search syntax

In its simplest form, a search criterion consists of a single word. However, the search panel allows you to create composite criteria.

Search Criteria	Sample Image	Description
Mask: criterion Example: maria		Example description: selects records that contain the “maria” string in any search column.
Mask: column:criterion Example: contact:maria		End-users can search against a specific column by preceding a search string with the column’s caption plus a colon character. Instead of the complete caption, it is possible to use the caption’s initial characters to perform a search against the first column whose name starts with the specified substring. To search against a column whose caption contains space characters, specify the column’s display caption in quotation marks. If the search string contains multiple conditions separated by space characters, and at least one condition defines a search against a specific column, the tree list displays only records that match all of these conditions (conditions are combined by the AND logical operator). Example description: selects records that contain “maria” in the column that starts with “contact”.
Mask: criterion1 criretion2 Example: maria anders	Option 1 Option 2	If the search string contains multiple words separated by space characters, the words are considered as individual conditions. Use the ASPxGridSearchPanelSettings.GroupOperator property to specify a logical operator used to combine the conditions. Option 1 (default behavior) When the ASPxGridSearchPanelSettings.GroupOperator property is set to And. Only records that match all of the conditions are shown (that is, the conditions are combined by the AND logical operator). Example description: selects records that contain both “maria” AND “anders” strings in any search column. Option 2 When the ASPxGridSearchPanelSettings.GroupOperator property is set to Or. If there is no column specification, the tree list displays records that match at least one of these conditions (the conditions are combined by the OR logical operator). If at least one condition defines a search against a specific column, the tree list displays only records that match all of these conditions (conditions are combined by the AND logical operator). Example description: selects records that contain either “maria” OR “anders” strings in any search column.
Mask: “criterion with spaces” Example: “maria anders”		If you want to search for a string containing a space character, specify this string in quotation marks. Example description: selects records that contain “maria anders” in any search column.
Mask: criterion1 -criterion2 Example: maria -anders		Precede a condition with “-” to exclude records that match this condition from the resulting set. There should be no space between the “-” sign and the condition. Example description: selects records that contain “maria”, excluding records that contain “anders”.
Mask: criterion1 +criterion2 Example: maria +sweden		Precede a condition with “+” to display only records that match this condition. The “+” specifier allows you to implement the logical AND operator. There should be no space character between the “+” sign and the condition. Example description: selects records that contain both “maria” AND “sweden” in search columns.

Note

Searches performed using a Search Panel are case insensitive.

Online Demos

GridView - Search Panel