public interface GridFiltering
search criteriacan be applied to a
gridto filter the data being displayed.
Typically, there are two types of criteria that affect how a grid matches data:
dataSource, and never made available to users
combinedand used to match records.
Note, however, that attempts to fetch with more restrictive criteria may not result in a
ResultSets implement local filtering
adaptively and may not require a server-trip if a filter can be achieved from local caches.
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-rowthat allows users to apply search-values on a per-field basis. When
ListGrid.allowFilterOperatorsis true, the default, users can modify the
search operatorassigned 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.alwaysShowOperatorIconis true, the current operator is indicated in a small icon in each filter-field.
Developers can interact with a field's search operator with
Criteria in the filter-row reflects current public
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.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.getFilterEditorCriteria(), but are not shown to the user for editing.
may specify a field's
filterEditor-type, and this can be a custom
FormItem class that uses
canEditCriterion() to manage
the criteria it works with.
For more complicated cases or more control, developers can
Criteria from the filter-row is combined with other sources of criteria when data is fetched.
formoutside of the grid, that produces criteria, you can apply the criteria by passing it to
filterData. The primary difference between these two APIs is that
DSRequest.textMatchStyleof substring, so that records are matched by case-insensitive substring comparison.
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
If you need more power or variance than the filter-row provides, you can
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.
view-stateand via the
SavedSearchesfeature, which is turned on by default.