Persisting Settings

Serenity 2.1.5 introduced ability to persist grid settings including these details:

  • Visible Columns and Display Order
  • Column Widths
  • Sorted Columns
  • Advanced Filters (ones created with Edit Filter link on bottom right)
  • Quick Filters (as of writing, not yet available)
  • State of Include Deleted Toggle

By default, grids doesn’t automatically persist anything.

Thus, if you hide some columns and navigate away from Orders page, when you come back, you’ll see that those hidden columns became visible again.

You need to turn on persistance for all grids, or for individual ones that you want them to remember their settings.

Turning On Persistance by Default

DataGrid has a static configuration parameter with name DefaultPersistanceStorage. This parameter controls where grids save their settings automatically by default. It is initially null.

In ScriptInitialization.ts, you might turn on persistance for all grids by default like below:

  1. namespace Serene.ScriptInitialization {
  2.     Q.Config.responsiveDialogs = true;
  3.     Q.Config.rootNamespaces.push('Serene');
  5.     Serenity.DataGrid.defaultPersistanceStorage = window.sessionStorage;
  6. }

This saves settings to browser session storage, which is a key/value dictionary that preserves data while any browser window stays open. When user closes all browser windows, all settings will be lost.

Another option is to use browser local storage. Which preserves settings between browser restarts.

  1. Serenity.DataGrid.defaultPersistanceStorage = window.localStorage;

Using any of the two options, grids will start to remember their settings, between page reloads.

Handling a Browser that is Shared by Multiple Users

Both sessionStorage and localStorage is browser scoped, so if a browser is shared by multiple users, they’ll have same set of settings.

If one user changes some settings, and logs out, and other one logs in, second user will start with settings of the first user (unless you clear localStorage on signout)

If this is a problem for your application, you may try writing a custom provider:

  1. namespace Serene {
  2.     export class UserLocalStorage implements Serenity.SettingStorage {
  3.         getItem(key: string): string {
  4.             return window.localStorage.getItem(
  5.                 Authorization.userDefinition.Username + ":" + key);
  6.         }
  8.         setItem(key: string, value: string): void {
  9.             window.localStorage.setItem(
  10.                 Authorization.userDefinition.Username + ":" + key, value);
  11.         }
  12.     }
  13. }
  15. //...
  16. Serenity.DataGrid.defaultPersistanceStorage = new UserLocalStorage();

Please note that this doesn’t provide any security. It just lets users have separate settings.

Setting Persistance Storage Per Grid Type

To turn on persistance, or change target storage for a particular grid, override getPersistanceStorage method:

  1. namespace Serene.Northwind {
  2.     //...
  3.     export class OrderGrid extends Serenity.EntityGrid<OrderRow, any> {
  4.         //...
  6.         protected getPersistanceStorage(): Serenity.SettingStorage {
  7.             return window.localStorage;
  8.         }
  9.     }
  10. }

You may also turn off persistance for a grid class by returning null from this method.

Determining Which Setting Types Are Saved

By default, all settings noted at start are saved, like visible columns, widths, filters etc. You may choose to not persist / restore specific settings. This is controlled by getPersistanceFlags method:

  1. namespace Serene.Northwind {
  2.     //...
  3.     export class OrderGrid extends Serenity.EntityGrid<OrderRow, any> {
  4.         //...
  6.         protected getPersistanceFlags(): GridPersistanceFlags {
  7.             return {
  8.                 columnWidths: false // dont persist column widths;
  9.             }
  10.         }
  11.     }
  12. }

Here is the set of complete flags: 

  1. interface GridPersistanceFlags {
  2.     columnWidths?: boolean;
  3.     columnVisibility?: boolean;
  4.     sortColumns?: boolean;
  5.     filterItems?: boolean;
  6.     quickFilters?: boolean;
  7.     includeDeleted?: boolean;
  8. }

When Settings Are Saved / Restored

Settings are automatically saved when you change something with a grid like:

  • Choosing visible columns with Column Picker dialog
  • Resizing a column manually
  • Editing advanced filter
  • Dragging a column, changing position
  • Changing sorted columns

Settings are restored on first page load, just after grid creation.

Persisting Settings to Database (User Preferences Table)

Serene 2.1.5 comes with a UserPreferences table that you may use as a persistance storage. To use this storage, you just need to set it as storage similar to other storage types.

  1. /// <reference path="../Common/UserPreference/UserPreferenceStorage.ts" />
  3. Serenity.DataGrid.defaultPersistanceStorage = new Common.UserPreferenceStorage();

Don’t forget to add reference statement, or you’ll have runtime errors, as TypeScript has problems with ordering otherwise.

OR 

  1. namespace Serene.Northwind {
  2.     //...
  3.     export class OrderGrid extends Serenity.EntityGrid<OrderRow, any> {
  4.         //...
  6.         protected getPersistanceStorage(): Serenity.SettingStorage {
  7.             return new Common.UserPreferenceStorage();
  8.         }
  9.     }
  10. }

Manually Saving / Restoring Settings

If you need to save / restore settings manually, you may use methods below:

  1. protected getCurrentSettings(flags?: GridPersistanceFlags): PersistedGridSettings;
  2. protected restoreSettings(settings?: PersistedGridSettings, flags?: GridPersistanceFlags): void;

These are protected methods of DataGrid, so can only be called from subclasses.