Filter Summaries

Objective

There are many scenarios in which showing a summary of the filters that were used in a grid is needed. This may be useful when filters may not be visible all the time. When they are not visible a summary of the filters values is shown, so users are aware of which filters are applied. An example of this scenario is present in the K2BOrion theme, where the filters section may be collapsed.

Two ways of displaying the filter summary are available in K2BTools:

  1. As a string showing the filter values.
    FilterSummaryTextRunTime
    Filter Summary "Text"

  2. As a set of Tags, each representing a filter value.
    FilterSummaryTagsRunTime
    Filter Summary "Tags"

The second option was implemented in K2BTools 12.3. When using this option, the UI also allows the user to clear specific filters, by deleting the corresponding tag.

Before using this feature

Make sure that this feature is supported by your layout object. See Customizing filters UI in Basic Layout objects for more information.

Customizing the filter summary

This feature can be customized globally for a KB and also por each grid.

In the General Settings node, the developer can configure which render should be used by default using the "Filter Summary Render" property.

The developer can also customize how this feature is implemented in each Filters node, using the "Summary Generator" procedure. The summary generator is a procedure in the KB that receives the filter values and prepares the information that should be shown in the summary. This procedure can return a Character value, or an instance of the K2BValueDescriptionCollection SDT.

If a character value is returned, a "Text" filter summary is shown. If an instance of the K2BValueDescriptionCollection SDT is returned, a "Tags" render is used. By default, the generators referenced in this property match the "Filter Summary Render" property value in the KB configuration. If changed manually, the render defined by this property takes precedence over the one defined in the configuration.

Summary Generator Procedure (for "Text" render)

These generators' parm rules must match this structure:

  • In:ProgramName: &PgmName of the object that has the filter
  • In:GridName: Name of the grid
  • In: K2BFilterValuesSDT: An SDT with all filters descriptions and values.
  • Out: SummaryText: a text with the filters summary.

Summary Generator Procedure (for "Tags" render)

These generators' parm rules must match this structure:

  • In:Program Name: &PgmName of the object that has the filter
  • In:GridName: Name of the grid
  • In: K2BFilterValuesSDT: An SDT with all filters descriptions and values.
  • Out: K2BTagCollection: Created using the K2BValueDescriptionCollection SDT, returns the content for each tag.

Auxiliary procedures

Summary generators call other procedures to serialize the values of each filter into a string. These procedures may be modified by the developer.

K2BGetStandardFilterSummary

It is called for standard filters. It receives the “ValueDescription” of the filter and returns the summarized information of this filter.

K2BGetDateTimeRangeFilterValueSummary

It is called for Filters of Type “DateRange” with a DateTime type. It receives the “SemanticDateRangeValue”, the “DateRangeFromValue” and the “DateRangeToValue”.
Returns the summarized information of this filter.

K2BGetDateRangeFilterValueSummary

It is called for Filters of “Type” “Date” based on “Date”. It receives the “SemanticDateRangeValue”, the “DateRangeFromValue” and the “DateRangeToValue”.

Returns the summarized information of this filter.

K2BGetMultipleFilterValueSummary

It is called for Filters of Type “Multiple”. It receives a “MultipleValues” collection, and returns the summarized information of this filter.

K2BJoinFilterValues

It’s called after the iteration of all filters has finished by "Text" summary generators. It receives a collection of filter descriptions and values, and returns the summary text.

K2BAttributeValueSDTStructure
"K2BAttributeValueSDT" structure

  • AttributeName: description of the filter.
  • AttributeValue: The value the filter has.