Customizing filters UI in Basic Layout objects

Introduction

From K2BTools 11.0 onwards, filters have been enhanced to support the inclusion of Generic Filters. In order to use this new type of filter, layouts must specify how that filter should be displayed.

Moreover, the layout objects must specify how the filters should be shown regardless of their composition. Instances may or may not contain generic and detailed filters. Because of this, the following scenarios are possible:

  1. Having no filters.
  2. Having detailed filters only.
  3. Having generic filters only.
  4. Having both types of filter.

The UI for these scenarios should be consistent, but slight variations can exist among them. To provide as much flexibility as possible, K2BTools allows the developer to specify them separately, leaving the consistency among them up to the developer.

This page details how these changes should be done inside Basic Layout? objects.

Notes:

  1. Supporting generic filters is not mandatory. The developer can choose to continue using filters as in older versions. In that case changes to the layout objects are not necessary.
  2. K2BTools scans the layout object to determine whether it includes support for generic filters. If it does, the new logic is used. If not, the old one is used. This does not require any configuration from the developer.
  3. This page details how the filters should be specified. These changes should be performed in the layout object(s) that are used to generated the objects the developer wishes to configure.

Configuring filters - versions before K2BTools 11 (Backwards compatibility)

In previous versions, K2BTools only required one control in the layout object related to filters.

That control was the “FiltersContainer” table. When applying K2BTools, this table is replaced with the contents of the “Detailed filters” specified in the instance.

In K2BTools 10.4, two optional controls were added to the layout object.

The first is the “FilterSummary” textblock. When K2BTools detects the presence of a textblock with this control name, the “Filter Summary” feature becomes available and the textblock’s caption is updated in runtime to show the filter summary generated from the filter values.

The second is the “FilterGlobalContainer” table. If that table is present in the layout and the instance has no detailed filters, the entire table is deleted from the generated object. This can be used to wrap the filters in a table providing more UI elements. In particular, this can be used to contain both the “FiltersContainer” table and the “FilterSummary” textblock.

Current layout configuration

This section is valid from version 11.0 onwards. In order to use this configuration, the layout object must contain a table with control name “FilterGlobalContainer”, containing three tables: “OnlyGenericFilterLayout”, “OnlyDetailedFilterLayout”, and “CombinedFilterLayout”.

Each of those tables support one of the scenarios enumerated above (Having no filters, having generic filters only, having detailed filters only, and having both types of filters). The basic idea is that only one of the tables is copied to the layout object, depending on which scenario is being generated. In the case of the first scenario (no filters), the “FilterGlobalContainer” table is deleted (along with all its children).

FilterLayoutConfiguration
Filter layout usage depending on filters used

Generic filter configuration

The generic filter must be present in the “CombinedFilterLayout” and “OnlyGenericFilterLayout” tables. To do so, a variable called “K2BToolsGenericSearchField” must be added. When generating an object based on the layout, K2BTools will maintain this control as is, the only change done on it is changing the “Invite Message” for the control.

Detailed filters configuration

Detailed filters must be configured inside the “CombinedFilterLayout” and the “OnlyDetailedFilterLayout” tables. To do so, a table must be added to them. The control name for that table is “FiltersContainer_Combined” in the first case, and “FiltersContainer_OnlyDetailed” in the second.

When generating an object with K2BTools, this table will be replaced with the detailed filters content specified in the instance.

Filter summary configuration

Including the filter summary feature is optional. However, if present in the layout it must be present in both the “CombinedFilterLayout” table and the “OnlyDetailedFilterLayout” table.

To do so, include a textblock called “FilterSummary_Combined” or “FilterSummary_OnlyDetailed”, depending on the table.

When generating an object with K2BTools this control will be copied to the generated form with no modifications.

Adding code in the layout’s events

Basic Layouts support the addition of code in the Events part. This code is copied to the generated object.

The developer may need to include code related to the filters in the events part. In that case, it is important that the code should be included only when filters are present, and often only in certain scenarios.

To do so, the developer can define code slots. An example is shown below:

Event Start

//+ If.CombinedFilters

    FilterCollapsibleSection_Combined.Visible = False

//-

 

//+ If.OnlyDetailedFilter

    FilterCollapsibleSection_OnlyDetailed.Visible = False

//-

EndEvent

Code sample

In this case, the third line will be included only when combined filters are being used, and the same goes for the “If.OnlyDefailedFilters” section below (in that case, the code is only added when detailed filters are present and the generic filter is not).

Available slots are:

Slot Code is included when

If.Filters

Filters (of any kind) exist.

If.OnlyGenericFilter

Generic filter is included but detailed filters are not.

If.OnlyDetailedFilter

Detailed filters are included but the generic filter is not.

If.CombinedFilters

Both types of filters are included.