public interface GridFiltering
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:
grid or its
dataSource, and never made
available to users
explicit criteria are
combined and 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-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
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
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.
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.
form outside 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
filterData applies a
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.
SavedSearches feature, which is turned on by default.