Vertical Grid Search Panel
- 7 minutes to read
The Search Panel provides end-users with an easy and straightforward way to locate data by typing the filter criterion in the panel editor and highlights the search results.
To enable the search panel, set the ASPxGridSearchPanelSettings.Visible property to true. You can access the panel settings by using the ASPxVerticalGrid.SettingsSearchPanel property.
By default, a search panel filter criterion is applied automatically after the time period specified by the ASPxGridSearchPanelSettings.Delay property passes. You can disable the time delay by setting the ASPxGridSearchPanelSettings.AllowTextInputTimer property to false. In this case, the filter criterion is not applied automatically. 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. To learn more, see 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, search panel highlighting 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 ASPxGridSearchPanelSettings.HighlightResults, or define a VerticalGridDataRow.DataItemTemplate for this row and manually 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.
<dx:ASPxVerticalGrid ID="VerticalGrid" runat="server" DataSourceID="GridDataSource" >
<Rows>
...
</Rows>
<SettingsSearchPanel Visible="true" ShowApplyButton="True" ShowClearButton="True" />
</dx:ASPxVerticalGrid>
On the client side
The code sample below demonstrates how to specify the search panel filter in code on the client side using the ASPxClientVerticalGrid.ApplySearchPanelFilter method.
<dx:ASPxVerticalGrid ID="VerticalGrid" runat="server" DataSourceID="GridDataSource" ClientInstaceName="verticalGrid" >
<Rows>
...
</Rows>
<SettingsSearchPanel Visible="True" ShowApplyButton="True" ShowClearButton="True" />
</dx:ASPxVerticalGrid>
verticalGrid.ApplySearchPanelFilter('big');
Note
The ASPxGridBase.SearchPanelFilter property and the ASPxClientVerticalGrid.ApplySearchPanelFilter method are in effect even if the search panel is disabled (the ASPxGridSearchPanelSettings.Visible property is set to false).
How to specify the rows to which the search panel filter will be applied
By default, the search panel filter is applied to all visible rows in the grid.
You can specify particular rows to which the filter should be applied using the ASPxVerticalGridSearchPanelSettings.RowNames property. The property lists row identifiers that can be either: a row name (WebColumnBase.Name), field name (VerticalGridDataRow.FieldName), or caption(WebColumnBase.Caption).
<dx:ASPxVerticalGrid ID="VerticalGrid" runat="server" DataSourceID="SqlDataSource1">
<rows>
<dx:VerticalGridTextRow FieldName="CompanyName" Fixed="False" Height="0" VisibleIndex="1">
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="ContactName" Fixed="False" Height="0" VisibleIndex="2">
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="Address" Fixed="False" Height="0" VisibleIndex="3">
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="City" Fixed="False" Height="0" VisibleIndex="4">
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="Country" Fixed="False" Height="0" VisibleIndex="5">
</dx:VerticalGridTextRow>
</rows>
<SettingsSearchPanel RowNames="ContactName; CompanyName" ShowApplyButton="True" ShowClearButton="True" Visible="True" />
</dx:ASPxVerticalGrid>
To exclude a particular row from filtering, set the row’s GridDataColumnSettings.AllowFilterBySearchPanel property to false.
<dx:ASPxVerticalGrid ID="VerticalGrid" runat="server" DataSourceID="SqlDataSource1">
<rows>
<dx:VerticalGridTextRow FieldName="CompanyName" Fixed="False" Height="0" VisibleIndex="1">
<Settings AllowFilterBySearchPanel="False" />
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="ContactName" Fixed="False" Height="0" VisibleIndex="2">
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="Address" Fixed="False" Height="0" VisibleIndex="3">
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="City" Fixed="False" Height="0" VisibleIndex="4">
</dx:VerticalGridTextRow>
<dx:VerticalGridTextRow FieldName="Country" Fixed="False" Height="0" VisibleIndex="5">
</dx:VerticalGridTextRow>
</rows>
<SettingsSearchPanel ShowApplyButton="True" ShowClearButton="True" Visible="True" />
</dx:ASPxVerticalGrid>
How to change the default search panel editor with a custom one
The ASPxVerticalGrid provides two capabilities for using a custom editor for a search panel. The first is replacing the default editor with another DevExpress editor in the ASPxVerticalGrid.SearchPanelEditorCreate event handler.
<dx:ASPxGridView ID="Grid" runat="server" OnSearchPanelEditorCreate="Grid_SearchPanelEditorCreate">
<SettingsSearchPanel Visible="true" ShowApplyButton="True" ShowClearButton="True" />
<%--...--%>
</dx:ASPxGridView>
protected void Grid_SearchPanelEditorCreate(object sender, DevExpress.Web.ASPxGridViewSearchPanelEditorCreateEventArgs e) {
e.EditorProperties = new SpinEditProperties();
}
The second option of using a custom editor for the search panel is to specify an external DevExpress editor with the ASPxGridSearchPanelSettings.CustomEditorID property.
<dx:ASPxGridView ID="Grid" runat="server">
<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 |
| Example description: selects records that contain the “maria” string in any search column. |
Mask: column:criterion Example: contact:maria |
| You can search against a specific row by preceding a search string with the row’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 row whose name starts with the specified substring. If you want to search against a row whose caption contains space characters, specify the row’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 row, only records that match all of these conditions are shown (i.e., the conditions are combined by the AND logical operator). Example description: selects records that contain “maria” in the row whose name (the FieldName property) 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 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 (i.e., the conditions are combined by the AND logical operator). Example description: selects records that contain both “maria” AND “anders” strings in any search row. Option 2 When the ASPxGridSearchPanelSettings.GroupOperator property is set to Or. If there is no row specification, records that match at least one of these conditions are shown (i.e., the conditions are combined by the OR logical operator). If at least one condition defines a search against a specific row, only records that match all of these conditions are shown (i.e., the conditions are combined by the AND logical operator). Example description: selects records that contain either “maria” OR “anders” strings in any search row. |
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 row. |
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 rows. |
Note
Searches performed using 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.