User preference persistence module

Introduction

In interfaces generated using K2BTools the user is allowed to select the columns he desires in a grid and set how many rows per page he wants to see. By default this configuration is persisted in session and K2BTools provides procedures that the developer can extend in order to give an implementation of how these preferences are stored.

Since K2BTools 11, a module is provided by K2BTools, helping the developer to persist the configuration selected by the user. This information is stored in the database, so when the user returns to the application all the configuration previously selected will be remembered.

This module also allows advanced configuration, for example showing different  columns depending on the tenant of the application, or making global rules for an application that will be installed in different environments and should have a different default configuration in each environment.

The installation of this module is optional. To do so, follow the instructions in User Preference Persistence Backend installation.

The module includes a UI for advanced end users. See more information about this UI in User Preference Persistence Backend runtime configuration.

Grid column visibility persistence design

UserPreferencesPersistenceDesign
User persistence design

Saving the user selection

The user can select which columns should be visible using the “Grid Settings” menu. When the grid settings are saved, the flow on the left is executed.

The basic objects included by default by K2BTools implement a cache in the web session. After saving the selection in the cache they call the “PersistGridColumns” procedure in the user preference module.

The “PersistGridColumns” procedure saves the selection in the “GridColumn” table. This table stores the selection and:

  1. The user that saved the selection. (If this field is null, the configuration applies to all users not having a specific configuration).
  2. The “tenant” active at the moment.
  3. The program name of the web panel.
  4. The grid’s control name (to support web panels with many grids).

The backend contains UIs to update the GridColumn table. A privileged user can delete records from it and update current records to leave the “user” field blank. As was said before, when the user is left blank the configuration is used for all users with no configuration for that grid.

Loading the grid state

When the user enters a web panel containing a grid (that supports runtime column selection) K2BTools must determine the visibility status for each column. To do that, the flow on the right is executed.

First, K2BTools invokes basic objects that read from the web session cache mentioned in the previous section.

When the session cache is empty, the user preferences persistence module is called using the “Retrieve Grid Columns” procedure.

This procedure tries to get the grid column’s status from several sources, in this order:

  1. The “GridColumn” table, searching for a record with matching user, tenant, program name, and grid name.
  2. The “GridColumn” table, searching for a record with matching tenant, program name, and grid name. (Leaving the user empty).
  3. The “VisibleColumnRule” table, as explained below.

The VisibleColumnRule table can be used via the user preferences backend to create global visibility rules that apply to all grids. A privileged user can create rules that set the visibility value for columns matching certain criteria. Two types of criteria are available:

  1. Column name matches: In this case the user must provide the desired column name. The rule applies to columns matching that value exactly.
  2. Regular expression: In this case the user must provide a regular expression. The rule applies to columns whose name matches the regular expression provided.

The rules are evaluated separately for each column. First, rules matching the column name exactly are applied. If no rule of that type exists, then the column name is matched against the regular expressions and their corresponding rules are applied.

If the column does not match any rule, the visibility status is loaded from the “Selected by Default” property in the knowledge base”.

Page size persistence

When the user configures the page size for a grid in the application’s UI, that configuration is stored in a table in the module called RowsPerPage. This page has a structure similar to the GridColumn table, with Tenant, User, Program Name, and Grid Name columns.

When a grid is loaded, the module reads this table to load the page size. To do this, the module tries several queries, starting with one specific to the user/grid combination. If no results are found, more generic queries are tried until one of them is found. If all queries return no data, then the default value configured in the KB is used.

PageSizeQueries
Queries done to get page size for current user