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 ResultSets 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.