Package com.smartgwt.client.docs

# Interface GridFiltering

public interface GridFiltering

### Grid Filtering Overview

This overview discusses various ways that `search criteria` can be applied to a `grid` to filter the data being displayed.

Typically, there are two types of criteria that affect how a grid matches data:

- Implicit criteria - hidden criteria, applied by the developer, to the `grid` or its `dataSource`, and never made available to users
- Explicit criteria - public criteria, which may be applied by the developer or entered by the user - this criteria may be displayed to and modified by the user at runtime in various ways

A grid may have both implicit criteria, and explicit criteria that may come from multiple sources. When data is fetched, the implicit-criteria and any sources of `explicit criteria` are `combined` and used to match records.

Note, however, that attempts to fetch with more restrictive criteria may not result in a server-trip, because `ResultSet`s implement local filtering adaptively and may not require a server-trip if a filter can be achieved from local caches.

#### Initial Filter Criteria

You can provide an initial filter for a grid by setting `implicit criteria`, which is never shown to the user, or `initial criteria`, which may be shown for editing in the grid's builtin `filter-row`. You can also provide both types, if only some parts of the criteria should be public.

#### Filter Row Criteria

Grids provide a `filter-row` that allows users to apply search-values on a per-field basis. When `ListGrid.allowFilterOperators` is true, the default, users can modify the `search operator` assigned to a given field via the grid's `header context-menu`, allowing for more complex matching. If the selected operator is not the field's `default operator`, or if `ListGrid.alwaysShowOperatorIcon` is true, the current operator is indicated in a small icon in each filter-field.

Developers can interact with a field's search operator with `ListGrid.getFieldSearchOperator()`, `ListGrid.setFieldSearchOperator()` and `ListGrid.clearFieldSearchOperator()`.

Criteria in the filter-row reflects current public criteria that `can be edited`. Developers can retrieve this criteria with `ListGrid.getFilterEditorCriteria()` and set it with `ListGrid.setFilterEditorCriteria()`. When the filter-row is showing, Calls to APIs such as `ListGrid.setCriteria()` or `ListGrid.fetchData()` will apply criteria to the filter-row, if the editors there allow it. Any criteria applied by these methods, that cannot be edited by the associated field's filter-editor, are still applied to fetches and will be returned by calls to `ListGrid.getCriteria()` or `ListGrid.getFilterEditorCriteria()`, but are not shown to the user for editing.

Developers may specify a field's `filterEditor-type`, and this can be a custom `FormItem` class that uses `getCriterion()`, `setCriterion()` and `canEditCriterion()` to manage the criteria it works with.

For more complicated cases or more control, developers can implement `ListGrid.filterEditorSubmit()`.

Criteria from the filter-row is combined with other sources of criteria when data is fetched.

#### External Criteria

If you have external logic, or a `form` outside of the grid, that produces criteria, you can apply the criteria by passing it to `fetchData` or `filterData`. The primary difference between these two APIs is that `filterData` applies a `DSRequest.textMatchStyle` of substring, so that records are matched by case-insensitive substring comparison.

If you have the `FilterEditor` showing, these external criteria will be appear in the filterEditor, where supported. Developers can apply additional external criteria without that effect by passing them to `DataBoundComponent.setImplicitCriteria()`, or by setting `ListGrid.searchForm` to the external criteria form.

If you need more power or variance than the filter-row provides, you can set `ListGrid.allowFilterWindow` to show a full-blown `FilterBuilder`, to construct more complex criteria that can also include logical operators like or.

All sources of criteria are combined to match records when data is fetched.

#### Saving Criteria

Grid criteria can be saved and restored with `view-state` and via the `SavedSearches` feature, which is turned on by default.