User preference persistence module


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.

Identifying the current user and tenant

The module calls K2BGetUserCode() and K2BGetTenantCode() to determine the current user and tenant. The application developer must change them as needed according to the application needs.

Grid column visibility persistence design

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.

Queries done to get page size for current user

Grid view persistence

When the user saves Grid views for a grid in the application's UI, that configuration is stored in a table in the module called GridView. The table has a structure with the grid and program name, the user name, the selected view name, two boolean fields (GridStateSaved, ColumnStateSaved) to check if each state is saved and two VarChar fields with the state of the GridState (filters and orders) and the ColumnsState (selected columns).

Grid View Table

Note: Up to K2BTools version 14.0, grid views stored in this module were available to all users, regardless of who created the view. From version 14.0 onwards, views are only available to the user that created them. To make a grid view available for all users, the UserCode column must be set to null. You can do this using the "Make Public" action in the grid views work with.