Skip to main content

Grid View Search Panel

  • 6 minutes to read

The Search Panel allows end users to type filter criteria in the panel editor to locate data. The search results are highlighted.

Set the Visible property to true to display the search panel. To access the panel settings, use the SettingsSearchPanel property.

The Delay property specifies the time period after which the search panel’s filter criteria is automatically applied to the control. To disable the time delay, set the AllowTextInputTimer property to false. In this case, the grid does not apply filter criteria automatically. A user can click the Apply (Search) button or press the Enter key to apply the criteria.

Set the ShowApplyButton and ShowClearButton properties to true to display the Apply and Clear buttons.

SearchPanel

Note

Search Panel Limitations

  • Search results contained in templates are not highlighted automatically, but you can highlight these results manually. See the following Support Center example to learn more: Code Example T222691: ASPxGridView - Search Panel - How to highlight the text placed inside a DataItem template.
  • When grid text contains HTML tags and the EncodeHtml property is set to false, the search panel highlight feature may break the current HTML structure.

    When text contains HTML tags, its appearance is controlled by the browser. Our search logic takes all 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 the ASPxGridSearchPanelSettings.HighlightResults property or specify the GridViewDataColumn.DataItemTemplate property for this column, and manually prevent highlighting if the entered text contains HTML tags.

How to apply a search panel filter in code

You can apply a search panel filter in code on the server side using the SearchPanelFilter property or on the client side using the ApplySearchPanelFilter(value) method.

SearchPanel_SearchPanelFilter

// On the server side
Grid.SearchPanelFilter = "big";
// On the client side
grid.ApplySearchPanelFilter('big');
<dx:ASPxGridView ID="Grid" runat="server" DataSourceID="GridDataSource" >
     <SettingsSearchPanel Visible="true" ShowApplyButton="True" ShowClearButton="True" />
</dx:ASPxGridView>

Note

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

How to specify the columns to which the search panel filter will be applied

The ASPxGridView control applies the search panel filter to all visible data columns (the default setting).

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

SearchPanel_ColumnName

Web Forms:

<dx:ASPxGridView ID="Grid" runat="server" DataSourceID="GridDataSource">
    <SettingsSearchPanel Visible="true" ShowApplyButton="True" ShowClearButton="True" ColumnNames="ContactName; CompanyName" />
</dx:ASPxGridView>

MVC:

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

Set the column’s GridDataColumnSettings.AllowFilterBySearchPanel property to false to exclude a specific column from the filter.

SearchPanel_AllowFilterBySearchPanel

<dx:ASPxGridView ID="Grid" runat="server" DataSourceID="GridDataSource" AutoGenerateColumns="False">
     <Columns>
          <dx:GridViewDataTextColumn FieldName="ContactName" />
          <dx:GridViewDataTextColumn FieldName="CompanyName">
               <Settings AllowFilterBySearchPanel="False" />
          </dx:GridViewDataTextColumn>
          <dx:GridViewDataTextColumn FieldName="Address" />
          <dx:GridViewDataTextColumn FieldName="City" />
          <dx:GridViewDataTextColumn FieldName="Country" />
     </Columns>
     <SettingsSearchPanel Visible="true" ShowApplyButton="True" ShowClearButton="True" />
     ...
</dx:ASPxGridView>

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

The ASPxGridView allows you to use a custom editor instead of the default search panel. You can use one of the following techniques:

1.Specify a DevExpress editor in the ASPxGridView.SearchPanelEditorCreate event handler (e.EditorProperties).

SearchPanel_EditorCreate

<dx:ASPxGridView ID="Grid" runat="server" DataSourceID="GridDataSource" OnSearchPanelEditorCreate="Grid_SearchPanelEditorCreate">
     <Columns>
     ...
     </Columns>
     <SettingsSearchPanel Visible="true" ShowApplyButton="True" ShowClearButton="True" />
     ...
</dx:ASPxGridView>
protected void Grid_SearchPanelEditorCreate(object sender, DevExpress.Web.ASPxGridViewSearchPanelEditorCreateEventArgs e) {
     e.EditorProperties = new SpinEditProperties();
}
  1. Use the ASPxGridSearchPanelSettings.CustomEditorID property to specify an external DevExpress editor.

SearchPanel_CustomEditorID

<dx:ASPxGridView ID="Grid" runat="server" DataSourceID="GridDataSource">
     <Columns>
          ...
     </Columns>
     <SettingsSearchPanel CustomEditorID="ASPxTextBox1" />
     ...
</dx:ASPxGridView>

<dx:ASPxTextBox ID="ASPxTextBox1" runat="server" Width="170px">
</dx:ASPxTextBox>

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

EUD_Grid_SearchPanelCriterion1

Example description: selects records that contain the “maria” string in any search column.

Mask:

column:criterion

Example:

contact:maria

EUD_Grid_SearchPanelCriterion2

You 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 initial characters of the caption. A search will be performed against the first column whose name starts with the specified substring. If you want 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, only records that match these conditions are shown (the conditions are combined by the AND logical operator).

Example description: Selects records that contain “maria” in the column that starts with “contact”.

Mask:

criterion1 criterion2

Example:

maria anders

Option 1

EUD_Grid_SearchPanelCriterion3_v2

Option 2

EUD_Grid_SearchPanelCriterion3

If the search string contains multiple words separated by space characters, the words are treated 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 (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 no column is specified, records that match at least one of these conditions are shown (the conditions are combined by the OR logical operator). If at least one condition defines a search against a specific column, only records that match all of these conditions are shown (the 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”

EUD_Grid_SearchPanelCriterion4

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

EUD_Grid_SearchPanelCriterion5

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

EUD_Grid_SearchPanelCriterion6

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 executed with a Search Panel are case insensitive.

Searches using the search panel for case-sensitive data sources in Server Mode are not supported. The search panel always converts a search string to lower-case before searching.

See Also