Runtime column selection in grids

Introduction

In many scenarios the columns that must be shown in a Grid (WPD) cannot be defined statically in design time. This may happen due to several reasons:

  1. The developer is working on a product that may be installed in different clients with different needs, and thus the grid's columns should be different in each installation.
  2. End users may enter the same interfaces while performing different tasks, and because of these the information displayed in the grid must change to adapt to the task that is being performed.

To ilustrate the second option, consider the following example. A system contains a "Customers" grid. A sales representative may be interested in the amount the customer has bought in the past, while an employee working in accounting may be interested in the amount the customer owes the company.

Using this feature, mechanisms can be created to show the sales representative and the accountant the corresponding columns. Also, the end user could modify this selection in runtime to modify the columns shown.

Design-Time Configuration

In order to activate this feature, the developer must set the "Allow runtime column selection" property to "True" in the corresponding grid.

RuntimeColumnSelectionDesignTime
Design Time configuration

The default value for this property is taken from the "Allow Runtime Column Selection" property in K2BWebPanelDesigner Settings, K2BEntityServices Settings or K2BPrompt Settings, depending on the tool being used. Thus, if the property in each grid is set to its default value, the developer can modify the Settings property to globally change the behaviour of all grids.

When this property is activated in any given grid, the "Allow runtime column selection" property is added to all the grid columns. Using the column-level property, it is possible to select which columns can be hidden by the end user. The developer can also choose for each column if the column should be visible by default or not, using the "Selected By Default" property.

Runtime appearance

The runtime appearance of this feature depends on the UX configuration used.

K2BModern

The user appearance of the grid after activating this option is shown below. As you can see, a button is added below the grid's filters to enter the "Select Columns" action. After doing this, a popup is opened where the end user can select the columns he wishes to see in the grid. After saving and closing the popup object, the grid is updated.

RuntimeColumnSelectionRuntime
Runtime appearance

K2BFlat

When using this UX configuration, the runtime column selection UI is included in the grid settings control.

GridSettingsAppearance
Grid settings appearance

Extensibility and customization

This section applies to runtime column selection controls in the K2BModern UX configuration only.

To modify the behaviour of this feature two mechanisms exist: The layout object, and the modification of the basic objects.

Layout object modification

This mechanism can be used to modify where runtime column selection controls will be displayed in runtime.

As you can see in the "Runtime Appearance" section, this feature is accessed via a button located between the filters and the grid by default in the K2BModern UX configuration. The position of this button can be modified.

In the K2BFlat configuration, the controls are included in the grid settings node. The position where the grid settings control is generated can be modified.

For more details, see the K2BWebPanelDesigner Layout Object user guide.

Basic object modification

IMPORTANT: From K2BTools 11 onwards, K2BTools provides a standard module to handle the persistence of the columns selected by the user. This module can be used as-is, or used as a foundation for the persistence solution.

We strongly recommend using this module to modify this behaviour. See User preference persistence module.

Another option is to modify the basic objects included in the KB when K2BTools is first applied. These objects are shown in the following image:

RuntimeColumnSelectionBasicObjects
Runtime column selection basic objects

By doing this, you can acheive three goals:

  1. Modify the column selection popup appearance
  2. Add persistence to the column selection.
  3. Add default selections to match the needs of different users in the system.

To modify the appearance of the column selection popup, modify the web panel "K2BSelectColumns". This web panel can be modified as desired by the developer. Bear in mind that future versions of K2BTools may add features or bugfixes in this object, if that's the case the corresponding release notes will inform of the changes performed so that all developers can update their web panels.

To accomplish the second and third goals, the developer must modify "K2BPersistGridColumns" and the "K2BRetrieveGridColumns" procedures. The user can place any code he wishes into this procedures, for example to persist all the information to a table to remember the user's settings, or the creation of a default selection by loading the corresponding SDT with the columns that should be seen by the user according to his role or other properties.

Important: The "K2BPersistGridColumns" and the "K2BRetrieveGridColumns" procedures are different from "K2BLoadGridColumns" and "K2BSaveGridColumns" procedures. The latter are the ones invoked by the web panels containing the grids, and those interact with the persist and retrieve procedures if necessary.

The load and save procedures also interact with the user session to store the column selection temporarily. This was done because of two reasons:

  1. The performance is improved in database-based solutions as the information is fetched from the database only once.
  2. If the developer does not implement anything in the Persist and Retrieve procedures, the selection is stored in the session, avoiding the need to manually select the columns each time the user enters an interface containing a grid for which he had already selected the desired columns.

This can, however, prove to be a bad solution if the developer implements mechanisms in the Persist and Retrieve procedures that involve modifications to the column selection from a source different from the end user's session. For example, if a backend is given to an administrator that can be used to select the columns for each of the application's roles. In this case, if modifications are made the end user will see the result after the session cache is renewed (after the user logs out).

In that case, the developer may need to modify the Load and Save procedures also.

Security Considerations

Bear in mind that this feature is not intended as a security feature but as an usability feature. This means that if the developer hides a particular column the column will be invisible to an user entering the web panel via a web browser, but the value will be included in the HTML form. Thus, an user with HTML knowledge could extract the information from the column even if the column is set as hidden.