Persisting Settings

    • 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.

    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:

    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.

    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.             window.localStorage.setItem(
    9.                 Authorization.userDefinition.Username + ":" + key, value);
    10.         }
    11.     }
    12. }
    14. //...

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

    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. }
    1. interface GridPersistanceFlags {
    2.     columnVisibility?: boolean;
    4.     filterItems?: boolean;
    5.     quickFilters?: boolean;
    6.     includeDeleted?: boolean;
    7. }

    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.

    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. }

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

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