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.

How it works

Before using this feature, make sure that it is supported by your layout object. See Customizing filters UI in Basic Layout objects for more information.

Customizing filter summary text

By default the filter summary text will be shown like bellow.

FilterSummaryTextRunTime
"Filter Summary" text

All filters are separated by a “,” and each filter is shown with this format: “<description>: <value>”

The way the filter value is shown depends on the filter type.
This behaviour can be customized globally or for each grid of the application. For this purpose when the filter summary property is enabled in the filter node, the “Summary Generator” property will appear.

FilterNodeSummaryGeneratorProperty
"Summary Generator" property

In this property the developer can configure the procedure that is in charge of formatting the filter summary. By default the procedure called “K2BGetFilterSummary” is used, but the developer can change it.

Summary Generator Procedure

The summary generator procedures receives a

  • 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.
  • Returns a text with the filters summary.

The “K2BFilterValuesSDT” structure is shown below.

K2BFilterValuesSDTStructure
"K2BFilterValuesSDT" structure

Its fields are:

  • Name: Name of the filter. Contains the value for the “Name” property of the “Filter” node.
  • Description: Description of the filter.
  • Type: Type of the filter. The possible values are:
  • Standard: For filters of Type “Standard”
  • Multiple: For filters of Type “Multiple”.
  • DateRange: For filters of type “DateRange” based on a “Date”.
  • DateTimeRange: For filters of type “DateRange” and based on a “DateTime”
  • Value: The value of the filter.
  • ValueDescription: If input type of the filter variable is set to description the “Item Description” will be shown. Otherwise the ValueDescription field will be set with the “Item Value”.
  • SemanticDateRangeValue: For filters of type “DateRange” with “DateRangeType” “Semantic” , the Semantic description of the filter.
  • DateRangeFromValue: For filters of Type “DateRange”, the “From” value.
  • DateRangeToValue: For filters of Type “DateRange”, the “To” value.
  • MultipleValues: For filters of type “Multiple” a collection of:
    • ItemValue: The value of a selected filter.
    • ItemDescription: If “Input Type” of the variable is set to “Descriptions”, the Item Descripton value of the filter. Otherwise the Item Value will be shown.

Inside the K2BGetFiltersSummary procedure there are other auxiliary procedures that can also be customized.

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