Date filters generally define an interval where results should be located. Using “DateRange” filters, the developer can easily add a filter which will allow the user to define the interval setting its “From” and “To” date.
In many cases some intervals (relative to the current date) are used very frequently, sometimes even exclusively. In those cases, the user will probably prefer to select the interval, rather than selecting its start and end dates. To support this scenario, K2BTools includes three types of DateRange filters: “Manual”, "Dyanmic Range Set" and “Semantic”. The developer can choose among these types using the “Date Range Type” property.
When using Manual Date Range filters, the following UI will be generated.
|Date range filters, manual input type = TwoFields
Using this UI, the user can select both the start and end dates for the interval, with complete flexibility. The developer can determine the default values for the start and end of the interval. Additionally, developer can choose between two fields with its own calendar (as shown in the picture above) or only one field with a calendar (as it is shown in the example bellow).
|Date range filters, manual input type = OneField
Using this option, the end user is given a unified control to enter both the “From” and “To” values, where:
The current selection is highlighted.
Two months are shown, to simplify the selection of ranges starting in one month and finishing in the next one.
To select between one filed or two fields, date range filters have the “Manual Input Type” property that can be set either to “TwoFileds” or "OneField". The default value of this property when the filter datatype is date, (and is not a semantic filter) can be configured in the K2BTools General Settings
"Dynamic Range Set" and "Semantic" date range filters are equivalent from the end user's point of view: In both cases a list of options is presented and the user can choose a period in that list.
The "Dynamic Range Set" option was added in K2BTools 14.1. The "Semantic Filters" is still valid and is kept for backwards compatibility purposes.
In new KBs, we recommend using Dynamic Range Set filters instead of Semantic filters.
When using these types of filter, the following UI will be generated.
Using this UI, the user can quickly choose among the predefined options in the combobox. If the developer allows it, the user can also choose the “Other” option. When that option is selected, the UI will be updated like this.
The developer can customize the filter using the following properties:
- Semantic Date Ranges / Date Range Set Provider properties: Define the options present in the combobox and its default value. See more information below.
- Include Manual Option: Determines if the “Other…” option should be included.
- Date Range Empty Item, Date Range Empty Item Text: Determine if the “(All)” option should be included, and its caption.
- Range Selector Control: Defines the UI for the range selector list. May be "Combo", as in the previous examples, or "List", as in the example below.
|Range Selector Control = "List"
This property is used to select the dataprovider that returns the ranges available to the end user. To determine which ranges should be available by default, the developer must evaluate the data that will be filtered, and frequent values for the use case that the user will be executing.
In a banking application, the user may be able to see the movements in its accounts. In that case, the user may filter “By month” frequently. In that case, The ranges could be:
- Current Month
- Last Month
- 2 Months ago
In an ecommerce application, the user be searching for an order whose exact date he doesn’t remember, but can estimate. In that case, the user may find something like this attractive:
- Last 30 days
- Last 60 days
- Last 120 days
To perform this, the developer can chose a predefined dataprovider (already provided by K2BTools) or define its own.
|Data Range Set Provider dialog
When the developer defines its own dataprovider, the dataprovider must return the SDT named K2BDatetimeRangeSet. We strongly recommend opening and analyzing the code of the dataproviders already provided by K2BTools to see how the data provider's code should be defined. K2BT_DaysPeriodsBackwardsDatetimeRangeProvider is a good example.
|Dynamic Range Set Provider return SDT
For each date range the following fields must be defined:
- Code: A code that identifies the option. Must be unique in the collection.
- Description: The descrition that will be visible to the final user.
- FromValue: The range's start date.
- ToValue: The range's end date.
The DefaultValueCode field of the SDT can be used to define which will be the range selected by default when the user enters the panel.
The dataprovider selection dialog only shows the dataproviders that return the K2BDateTimeRangeSetSDT type.
If defining your own data provider, make sure that that's its return type.
We recommend using the Dynamic Range Set option whenever possible. Using that option simplifies the creation and administration of the date range set definitions.
This option is kept for compatibility reasons in migrated KBs.
This property is used to define the ranges available to the end user. To determine which ranges should be available by default, the developer must evaluate the data that will be filtered, and frequent values for the use case that the user will be executing.
K2BTools includes the definition for some common sets out of the box. The developer can redefine those sets, or create new ones. Also, those sets can be created for a particular filter or globally in the KB.
When creating a filter, the developer can choose from one of the globally-defined sets, or create a new independent set. To create an independent set the developer may override one of the default sets defined in a KB level. If the developer chooses not to override the set’s ranges, changes in the KB-level configuration will impact the filter.
|Date Range set definition
For each range, the developer must determine: its “InternalName”, an identifier inside the set, its “Description”, which should contain a GeneXus expression used to calculate the range description in runtime, and its “From” and “To” expressions, which will be used to calculate the From and To dates in runtime. If one of these expressions is empty, the range will not include its corresponding condition.
In this dialog, the developer may also select the default selected range. If left blank, the first available option will be selected by default.
To do this, use the “Default Semantic Date Ranges” property in K2BWebPanelDesignerSettings and K2BTools General Settings. The sets defined in this property will be available in the “Default Range Set” combo when defining a filter.