Using standard query filters in toolbar filters

You often use standard query filters with list views in the page configuration of the application user interface. The row iterators of list views support toolbar filter widgets. A toolbar filter lets users select from a drop-down menu of query filters to view subsets of the data that the list view displays. Standard query filters are one type of query filter that you can add.

You specify the standard query filters for a toolbar filter on the Filter Options tab. On the tab, you can add two kinds of filter options:

ToolbarFilterOption – An expression that resolves to a single object that implements the BeanBasedQueryFilter interface, such as a standard query filter.
ToolbarFilterOptionsGroup – An expression that resolves to an array of objects that implement the BeanBasedQueryFilter interface, such as standard query filters.

You can specify a standard query filter of an array of standard query filters by using an inline constructor in the filter property of a filter option. Alternatively, you can specify a Java or Gosu class that returns a standard query filter or an array of them.

Toolbar filter caching

Typically, list views cache the most recent toolbar filter selection made in a user’s session. If the user leaves a page and then returns to it, a list view retains and applies the toolbar filter option that was in effect when the user left the page.

You disable filter caching by setting the cacheKey property of a toolbar filter to an expression that evaluates to a potentially different value each time a user enters the page. For example, you might specify the following Gosu expression.

policy.PolicyNumber

If you disable filter caching, the list view reverts to the default filter option for entry to the page. You specify the default filter option by setting the selectOnEntry property on the option to true. Alternatively, you specify the default filter option by moving the option to the top of the list of options on the Filter Options tab.

Toolbar filter recalculation

Generally, list views calculate their filter options only once, when a user enters a page. Filter options remain unchanged during the life span of a page. Sometimes you need a list view to recalculate its filter options in response to changes that a user makes on a page.

You force a list view to recalculate its filter options in response to changes by setting the cacheOptions property of a toolbar filter to false. Set the property to false with caution, because the recalculation of filter options after a user makes changes can reduce the speed at which the application renders the updated page.

Example of a single toolbar filter option

The following example filter properties each specify a standard query filter by using an inline constructor. The filter applies to work queue tasks that the list view in the WorkQueueExecutorsPanelSet PCF file displays. WorkQueueExecutorsPanelSet is a separate PCF file included in WorkQueueInfo.pcf. The TaskFilter toolbar filter has two ToolbarFilterOption filter values:

new gw.api.filters.StandardQueryFilter("All", \ q -> {})
new gw.api.filters.StandardQueryFilter("With errors", 
        \ q -> q.compare("Exceptions", gw.api.database.Relop.GreaterThan, 0))

Note: The previous code block for the single-line filter option field in the PCF editor contains line breaks and extra spaces for readability. If you copy and paste this code, remove these line breaks and spaces to make the code valid.

The toolbar filter uses the first parameters of the filters to provide two options, “All” and “With errors”, in the toolbar filter drop-down menu.

For single filter options, you can override the text of the drop-down menu of with the label property. For localization purposes, you must specify the filter name or the label property as a display key, not as a String literal.

Example of a group toolbar filter option

The following example filters property combines the two filter properties in the WorkQueueExecutorsPanelSet PCF file to specify an array of two standard query filters by using inline constructors. This ToolbarFilterOptionGroup example replaces the two ToolbarFilterOption filter values on the TaskFilter toolbar filter:

new gw.api.filters.StandardQueryFilter[] { 
  new gw.api.filters.StandardQueryFilter("All", \ q -> {}),
  new gw.api.filters.StandardQueryFilter("With errors", 
          \ q -> q.compare("Exceptions", gw.api.database.Relop.GreaterThan, 0))}

Note: The previous code block for the single-line filters option field in the PCF editor contains line breaks and extra spaces for readability. If you copy and paste this code, remove these line breaks and spaces to make the code valid.

The toolbar filter displays the first parameters of the filters, “All” and “With errors”, as options in the toolbar filter drop-down menu. The drop-down menu displays them together and in the order that you specify in the array constructor.

Group filter options do not have a label property, so the text of the menu options comes only from the filter names. For localization purposes, you must specify the filter names as display keys, not as String literals.