Web Components Tree Grid State Persistence

The Ignite UI for Web Components State Persistence in Web Components Tree Grid allows developers to easily save and restore the grid state. When the IgcGridState is applied on the Web Components IgcTreeGridComponent, it exposes the GetState, GetStateAsString, ApplyState and ApplyStateFromString methods that developers can use to achieve state persistence in any scenario.

Supported Features

IgcGridState directive supports saving and restoring the state of the following features:

• Sorting
• Filtering
• Advanced Filtering
• Paging
• CellSelection
• RowSelection
• ColumnSelection
• RowPinning
• Expansion
• GroupBy
• Columns
  • Multi column headers
  • Columns order
  • Column properties defined by the IColumnState interface.

Usage

The getState method returns the grid state in a IgcGridStateInfo object, containing all the state info. Additional steps may be required in order to save it.

The GetStateAsString returns a serialized JSON string, so developers can just take it and save it on any data storage (database, cloud, browser localStorage, etc).

The developer may choose to get only the state for a certain feature/features, by passing in an array with feature names as an argument. Empty array will result to using the default state options.

<igc-tree-grid id="grid">
    <igc-grid-state id="gridState"></igc-grid-state>
</igc-tree-grid>
html

var gridState = document.getElementById('gridState') as IgcGridStateComponent;

// get an `IgcGridStateInfo` object, containing all features original state objects, as returned by the grid public API
const state: IgcGridStateInfo = gridState.getState();

// get all features` state in a serialized JSON string
const stateString: string = gridState.getStateAsString();

// get the sorting and filtering expressions
const sortingFilteringStates: IgcGridStateInfo = gridState.getState(['sorting', 'filtering']);
typescript

ApplyState - The method accepts a IgcGridStateInfo object as argument and will restore the state of each feature found in the object or specified features as second argument.

ApplyStateFromString - The method accepts a serialized JSON string as argument and will restore the state of each feature found in the JSON string or specified features as second argument.

gridState.applyState(gridState);
gridState.applyStateFromString(gridStateString);
gridState.applyState(sortingFilteringStates)
typescript

The Options object implements the IgcGridStateOptions interface, i.e. for every key, which is the name of a certain feature, there is the boolean value indicating if this feature state will be tracked. GetState/GetStateAsString methods will not put the state of these features in the returned value and ApplyState/ApplyStateFromString methods will not restore state for them.

gridState.options = { cellSelection: false, sorting: false };
typescript

The simple to use single-point API's allows to achieve a full state persistence functionality in just a few lines of code. Copy paste the code from below - it will save the grid state in the browser LocalStorage object every time the user leaves the current page. Whenever the user returns to main page, the grid state will be restored. No more need to configure those complex advanced filtering and sorting expressions every time to get the data you want - do it once and have the code from below do the rest for your users:

constructor() {
    window.addEventListener("load", () => { this.restoreGridState(); });
    window.addEventListener("beforeunload", () => { this.saveGridState(); });
}

// Using methods that work with IgcGridStateInfo object.
public saveGridState() {
    const state = this.gridState.getState();
    window.localStorage.setItem('grid-state', JSON.stringify(state));
}

public restoreGridState() {
    const state = window.localStorage.getItem('grid-state');
    if (state) {
        this.gridState.applyState(JSON.parse(state));
    }
}

// Or using string alternative methods.
public saveGridStateString() {
    const state = this.gridState.getStateAsString();
    window.localStorage.setItem('grid-state', state);
}

public restoreGridStateString() {
    const state = window.localStorage.getItem('grid-state');
    if (state) {
        this.gridState.applyStateFromString(state);
    }
}
typescript

Demo

EXAMPLE

DATA

TS

HTML

CSS

export class EmployeesNestedTreeDataItem {
    public constructor(init: Partial<EmployeesNestedTreeDataItem>) {
        Object.assign(this, init);
    }

    public Age: number;
    public HireDate: string;
    public ID: number;
    public Name: string;
    public Phone: string;
    public OnPTO: boolean;
    public ParentID: number;
    public Title: string;

}
export class EmployeesNestedTreeData extends Array<EmployeesNestedTreeDataItem> {
    public constructor(items: Array<EmployeesNestedTreeDataItem> | number = -1) {
        if (Array.isArray(items)) {
            super(...items);
        } else {
            const newItems = [
                new EmployeesNestedTreeDataItem(
                {
                    Age: 55,
                    HireDate: `2008-03-20`,
                    ID: 1,
                    Name: `Johnathan Winchester`,
                    Phone: `0251-031259`,
                    OnPTO: false,
                    ParentID: -1,
                    Title: `Development Manager`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 42,
                    HireDate: `2014-01-22`,
                    ID: 4,
                    Name: `Ana Sanders`,
                    Phone: `(21) 555-0091`,
                    OnPTO: true,
                    ParentID: -1,
                    Title: `CEO`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 49,
                    HireDate: `2014-01-22`,
                    ID: 18,
                    Name: `Victoria Lincoln`,
                    Phone: `(071) 23 67 22 20`,
                    OnPTO: true,
                    ParentID: -1,
                    Title: `Accounting Manager`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 61,
                    HireDate: `2010-01-01`,
                    ID: 10,
                    Name: `Yang Wang`,
                    Phone: `(21) 555-0091`,
                    OnPTO: false,
                    ParentID: -1,
                    Title: `Localization Manager`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 43,
                    HireDate: `2011-06-03`,
                    ID: 3,
                    Name: `Michael Burke`,
                    Phone: `0452-076545`,
                    OnPTO: true,
                    ParentID: 1,
                    Title: `Senior Software Developer`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 29,
                    HireDate: `2009-06-19`,
                    ID: 2,
                    Name: `Thomas Anderson`,
                    Phone: `(14) 555-8122`,
                    OnPTO: false,
                    ParentID: 1,
                    Title: `Senior Software Developer`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 31,
                    HireDate: `2014-08-18`,
                    ID: 11,
                    Name: `Monica Reyes`,
                    Phone: `7675-3425`,
                    OnPTO: false,
                    ParentID: 1,
                    Title: `Software Development Team Lead`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 35,
                    HireDate: `2015-09-17`,
                    ID: 6,
                    Name: `Roland Mendel`,
                    Phone: `(505) 555-5939`,
                    OnPTO: false,
                    ParentID: 11,
                    Title: `Senior Software Developer`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 44,
                    HireDate: `2009-10-11`,
                    ID: 12,
                    Name: `Sven Cooper`,
                    Phone: `0695-34 67 21`,
                    OnPTO: true,
                    ParentID: 11,
                    Title: `Senior Software Developer`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 44,
                    HireDate: `2014-04-04`,
                    ID: 14,
                    Name: `Laurence Johnson`,
                    Phone: `981-443655`,
                    OnPTO: false,
                    ParentID: 4,
                    Title: `Director`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 25,
                    HireDate: `2017-11-09`,
                    ID: 5,
                    Name: `Elizabeth Richards`,
                    Phone: `(2) 283-2951`,
                    OnPTO: true,
                    ParentID: 4,
                    Title: `Vice President`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 39,
                    HireDate: `2010-03-22`,
                    ID: 13,
                    Name: `Trevor Ashworth`,
                    Phone: `981-443655`,
                    OnPTO: true,
                    ParentID: 5,
                    Title: `Director`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 44,
                    HireDate: `2014-04-04`,
                    ID: 17,
                    Name: `Antonio Moreno`,
                    Phone: `(505) 555-5939`,
                    OnPTO: false,
                    ParentID: 18,
                    Title: `Senior Accountant`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 50,
                    HireDate: `2007-11-18`,
                    ID: 7,
                    Name: `Pedro Rodriguez`,
                    Phone: `035-640230`,
                    OnPTO: false,
                    ParentID: 10,
                    Title: `Senior Localization Developer`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 27,
                    HireDate: `2016-02-19`,
                    ID: 8,
                    Name: `Casey Harper`,
                    Phone: `0342-023176`,
                    OnPTO: true,
                    ParentID: 10,
                    Title: `Senior Localization`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 25,
                    HireDate: `2017-11-09`,
                    ID: 15,
                    Name: `Patricia Simpson`,
                    Phone: `069-0245984`,
                    OnPTO: false,
                    ParentID: 7,
                    Title: `Localization Intern`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 39,
                    HireDate: `2010-03-22`,
                    ID: 9,
                    Name: `Francisco Chang`,
                    Phone: `(91) 745 6200`,
                    OnPTO: false,
                    ParentID: 7,
                    Title: `Localization Intern`
                }),
                new EmployeesNestedTreeDataItem(
                {
                    Age: 25,
                    HireDate: `2018-03-18`,
                    ID: 16,
                    Name: `Peter Lewis`,
                    Phone: `069-0245984`,
                    OnPTO: true,
                    ParentID: 7,
                    Title: `Localization Intern`
                })
            ];
            super(...(newItems.slice(0, items)));
        }
    }
}
tsCOPY CODE

import 'igniteui-webcomponents-grids/grids/combined';
import { IgcGridComponent, IgcGridStateComponent, IgcGridStateOptions } from 'igniteui-webcomponents-grids/grids';
import { defineAllComponents, IgcButtonComponent, IgcCheckboxComponent, registerIconFromText } from 'igniteui-webcomponents';
import { EmployeesNestedTreeData } from './EmployeesNestedTreeData';
import "igniteui-webcomponents-grids/grids/themes/light/bootstrap.css";
import "./index.css";
defineAllComponents();

const restoreIcon = '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M480-120q-138 0-240.5-91.5T122-440h82q14 104 92.5 172T480-200q117 0 198.5-81.5T760-480q0-117-81.5-198.5T480-760q-69 0-129 32t-101 88h110v80H120v-240h80v94q51-64 124.5-99T480-840q75 0 140.5 28.5t114 77q48.5 48.5 77 114T840-480q0 75-28.5 140.5t-77 114q-48.5 48.5-114 77T480-120Zm112-192L440-464v-216h80v184l128 128-56 56Z"/></svg>';
const saveIcon = '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#000000"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M17 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.1 0 2-.9 2-2V7l-4-4zm2 16H5V5h11.17L19 7.83V19zm-7-7c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3zM6 6h9v4H6z"/></svg>';
const clearIcon = '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m256-200-56-56 224-224-224-224 56-56 224 224 224-224 56 56-224 224 224 224-56 56-224-224-224 224Z"/></svg>';
const forwardIcon = '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M647-440H160v-80h487L423-744l57-56 320 320-320 320-57-56 224-224Z"/></svg>';
const deleteIcon = '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M280-120q-33 0-56.5-23.5T200-200v-520h-40v-80h200v-40h240v40h200v80h-40v520q0 33-23.5 56.5T680-120H280Zm400-600H280v520h400v-520ZM360-280h80v-360h-80v360Zm160 0h80v-360h-80v360ZM280-720v520-520Z"/></svg>';
const refreshIcon = '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M480-160q-134 0-227-93t-93-227q0-134 93-227t227-93q69 0 132 28.5T720-690v-110h80v280H520v-80h168q-32-56-87.5-88T480-720q-100 0-170 70t-70 170q0 100 70 170t170 70q77 0 139-44t87-116h84q-28 106-114 173t-196 67Z"/></svg>';

export class Sample {

    private gridData;
    private grid: IgcGridComponent;
    private gridState: IgcGridStateComponent;
    public stateKey = 'tree-grid-state';

    public options: IgcGridStateOptions = {
        cellSelection: true,
        rowSelection: true,
        filtering: true,
        advancedFiltering: true,
        paging: true,
        sorting: true,
        groupBy: true,
        columns: true,
        expansion: true,
        rowPinning: true,
        columnSelection: true,
        moving: true
    };

    private columnsLoaded: Promise<void>;

    constructor() {
        var grid = this.grid = document.getElementById('grid') as IgcGridComponent;
        this.gridData = new EmployeesNestedTreeData();
        this.gridState = document.getElementById('gridState') as IgcGridStateComponent;

        var saveStateBtn = document.getElementById("saveState") as IgcButtonComponent;
        var restoreStateBtn = document.getElementById("restoreState") as IgcButtonComponent;
        var resetStateBtn = document.getElementById("resetState") as IgcButtonComponent;
        var leavePageBtn = document.getElementById("leavePage") as IgcButtonComponent;
        var leaveLink = document.getElementById("leaveLink") as HTMLElement;
        var clearStorageBtn = document.getElementById("clearStorage") as IgcButtonComponent;
        var reloadPageBtn = document.getElementById("reloadPage") as IgcButtonComponent;
        var allCheckboxes = Array.from(document.getElementsByTagName("igc-checkbox"));

        registerIconFromText("restore", restoreIcon, "material");
        registerIconFromText("save", saveIcon, "material");
        registerIconFromText("clear", clearIcon, "material");
        registerIconFromText("forward", forwardIcon, "material");
        registerIconFromText("delete", deleteIcon, "material");
        registerIconFromText("refresh", refreshIcon, "material");

        grid.data = this.gridData;
        grid.addEventListener("columnInit", (ev: any) => { this.onColumnInit(ev); });
        grid.allowAdvancedFiltering = true;
        grid.filterMode = 'excelStyleFilter';
        grid.columnSelection = 'multiple';
        grid.rowSelection = 'multiple';
        saveStateBtn.addEventListener('click', (ev: any) => { this.saveGridState(); });
        restoreStateBtn.addEventListener('click', (ev: any) => { this.restoreGridState(); });
        resetStateBtn.addEventListener('click', (ev: any) => { this.resetGridState(); });
        leavePageBtn.addEventListener('click', (ev: any) => { this.leavePage(); });
        leaveLink.addEventListener('click', (ev: any) => { this.saveGridState(); });
        clearStorageBtn.addEventListener('click', (ev: any) => { this.clearStorage(); });
        reloadPageBtn.addEventListener('click', (ev: any) => { this.reloadPage(); });

        allCheckboxes.forEach(cb => {
            cb.addEventListener("igcChange", (ev: CustomEvent) => { this.onChange(ev, cb.id); });
        });

        window.addEventListener("load", async () => {
            await this.columnsLoaded;
            this.restoreGridState();
        });
        window.addEventListener("beforeunload", () => { this.saveGridState(); });
    }

    public saveGridState() {
        const state = this.gridState.getStateAsString();
        window.localStorage.setItem(this.stateKey, state);
    }

    public restoreGridState() {
        const state = window.localStorage.getItem(this.stateKey);
        if (state) {
            this.gridState.applyStateFromString(state);
        }
    }

    public resetGridState() {
        const pagingState = { index: 0, recordsPerPage: 15, metadata: { countPages: 3, countRecords: this.gridData.length } };
        (this.grid as any).pagingState = pagingState;
        this.grid.clearFilter();
        this.grid.sortingExpressions = [];
        this.grid.groupingExpressions = [];
        this.grid.deselectAllColumns();
        this.grid.deselectAllRows();
        this.grid.clearCellSelection();
    }

    public onChange(event: CustomEvent, action: string) {
        if (action === 'allFeatures') {
            var allCheckboxes = Array.from(document.getElementsByTagName("igc-checkbox"));
            allCheckboxes.forEach(cb => {
                cb.checked = event.detail.checked;
            });
            for (const key of Object.keys(this.options)) {
                (this.gridState.options as any)[key] = event.detail.checked;
            }
        } else {
            (this.gridState.options as any)[action] = event.detail.checked;
            var allFeatures = document.getElementById("allFeatures") as IgcCheckboxComponent;
            allFeatures.checked = Object.keys(this.options).every(o => (this.gridState.options as any)[o]);
        }
    }

    public leavePage() {
        this.saveGridState();
        window.location.replace("./grids/tree-grid/state-persistence-about");
    }

    public clearStorage() {
        window.localStorage.removeItem(this.stateKey);
    }

    public reloadPage() {
        window.location.reload();
    }

    private onColumnInit(event: any) {
        if(event.detail.index === this.grid.columns.length - 1) {
           this.columnsLoaded = new Promise((resolve) => resolve());
        }
    }
}

new Sample();
tsCOPY CODE

<!DOCTYPE html>
<html>
  <head>
    <title>Sample | Ignite UI | Web Components | infragistics</title>
    <meta charset="UTF-8" />

    <link rel="shortcut icon" href="https://static.infragistics.com/xplatform/images/browsers/wc.png" >
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Kanit&display=swap" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Titillium Web" />
    <link rel="stylesheet" href="https://static.infragistics.com/xplatform/css/samples/shared.v8.css" />
    <link rel="stylesheet" href="/src/index.css" type="text/css" />
  </head>

  <body>
    <div id="root">
      <div class="sampleContainer">
          <div class="container horizontal">
            <igc-button id="restoreState" variant="contained">
              <igc-icon name="restore" collection="material"></igc-icon>
              Restore
            </igc-button>
            <igc-button id="saveState" variant="contained">
              <igc-icon name="save" collection="material"></igc-icon>
              Save
            </igc-button>
            <igc-button id="resetState" variant="contained">
              <igc-icon name="clear" collection="material"></igc-icon>
              Reset
            </igc-button>
            <igc-button id="leavePage" variant="contained">
              <igc-icon name="forward" collection="material"></igc-icon>
              Leave
            </igc-button>
            <igc-button id="clearStorage" variant="contained">
              <igc-icon name="delete" collection="material"></igc-icon>
              Clear
            </igc-button>
            <igc-button id="reloadPage" variant="contained">
              <igc-icon name="refresh" collection="material"></igc-icon>
              Reload
            </igc-button>
          </div>

          <div class="container horizontal">
            <ul>
                <li>Clicking the SAVE button or leaving the page <a id="leaveLink" href="./grids/tree-grid/state-persistence-about"><strong>here</strong></a> will save grid state to localStorage.</li>
                <li>Use the control buttons to SAVE / RESTORE / RESET / DELETE / grid state or LEAVE the page.</li>
                <li>Select/Deselect checkboxes to control saving / restoring feature state.</li>
            </ul>
          </div>

          <div class="container horizontal">
            <igc-checkbox id="allFeatures" checked>All Features</igc-checkbox>
            <igc-checkbox id="advancedFiltering" checked>Adv. Filtering</igc-checkbox>
            <igc-checkbox id="cellSelection" checked>Cell Selection</igc-checkbox>
            <igc-checkbox id="columns" checked>Columns</igc-checkbox>
            <igc-checkbox id="columnSelection" checked>Col Selection</igc-checkbox>
            <igc-checkbox id="expansion" checked>Expansion</igc-checkbox>
            <igc-checkbox id="filtering" checked>Filtering</igc-checkbox>
            <igc-checkbox id="paging" checked>Paging</igc-checkbox>
            <igc-checkbox id="rowPinning" checked>Row Pinning</igc-checkbox>
            <igc-checkbox id="rowSelection" checked>Row Selection</igc-checkbox>
            <igc-checkbox id="sorting" checked>Sorting</igc-checkbox>
            <igc-checkbox id="groupBy" checked>GroupBy</igc-checkbox>
            <igc-checkbox id="moving" checked>Moving</igc-checkbox>
          </div>

          <igc-tree-grid id="grid" name="grid" primary-key="ID" foreign-key="ParentID" width="98%" height="500px" auto-generate="false" moving="true" allow-filtering="true">
            <igc-grid-state id="gridState"></igc-grid-state>
            <igc-grid-toolbar>
              <igc-grid-toolbar-actions>
                <igc-grid-toolbar-hiding></igc-grid-toolbar-hiding>
                <igc-grid-toolbar-pinning></igc-grid-toolbar-pinning>
            </igc-grid-toolbar-actions>
            </igc-grid-toolbar>
            <igc-action-strip>
              <igc-grid-pinning-actions>
              </igc-grid-pinning-actions>
            </igc-action-strip>
            <igc-paginator></igc-paginator>

            <igc-column field="ID" header="ID" sortable="true" filterable="true" hidden="true"></igc-column>
            <igc-column field="Name" header="Name" sortable="true" filterable="true" pinned="true"></igc-column>
            <igc-column field="Title" header="Title" sortable="true" filterable="true"></igc-column>
            <igc-column field="Age" header="Age" sortable="true" filterable="true" groupable="true"></igc-column>
            <igc-column field="Phone" header="Phone" sortable="true" filterable="true"></igc-column>
            <igc-column field="OnPTO" header="On PTO" sortable="true" filterable="true" groupable="true"></igc-column>
          </igc-tree-grid>
        </div>
    </div>

    <!-- This script is needed only for parcel and it will be excluded for webpack -->
    <% if (false) { %><script src="src/index.ts"></script><% } %>
  </body>
</html>htmlCOPY CODE

/* shared styles are loaded from: */
/* https://static.infragistics.com/xplatform/css/samples */
.horizontal {
    gap: 10px;
    flex-basis: fit-content;
    flex-wrap: wrap;
}
.sampleContainer {
  padding: 0.5rem
}cssCOPY CODE

Edit in: Codesandbox

Like this sample? Get access to our complete Ignite UI for Web Components toolkit and start building your own apps in minutes. Download it for free.

Limitations

• getStateAsString method uses JSON.stringify() method to convert the original objects to a JSON string. JSON.stringify() does not support Functions, thats why the IgcGridState component will ignore the columns formatter, filters, summaries, sortStrategy, cellClasses, cellStyles, headerTemplate and bodyTemplate properties.