Web Components Grid State Persistence

The Ignite UI for Web Components State Persistence in Web Components Grid allows developers to easily save and restore the grid state. When the GridState is applied on the Web Components IgcGrid, it exposes the GridState.getState, GridState.getStateAsString, GridState.applyState and GridState.applyStateFromString methods that developers can use to achieve state persistence in any scenario.

Supported Features

GridState 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 IgcColumnState interface.

Usage

The GridState.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 GridState.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-grid id="grid">
    <igc-grid-state id="gridState"></igc-grid-state>
</igc-grid>

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']);

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

GridState.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)

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. GridState.getState/GridState.getStateAsString methods will not put the state of these features in the returned value and GridState.applyState/GridState.applyStateFromString methods will not restore state for them.

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

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);
    }
}

Restoring columns

GridState will not persist columns templates, column formatters, etc. by default (see limitations). Restoring any of these can be achieved with code on application level. Let’s show how to do this for templated columns:

1 - Define a template reference variable (in the example below it is #activeTemplate) and assign an event handler for the ColumnInit event:

<igc-grid id="grid">
    <igc-grid-state id="gridState"></igc-grid-state>
    <igc-column id="isActive" field="IsActive" header="IsActive"></igc-column>
</igc-grid>

constructor() {
    var grid = this.grid = document.getElementById('grid') as IgcGridComponent;
    var isActiveCol = this.isActive = document.getElementById('isActive') as IgcColumnComponent;
    this.onColumnInit = this.onColumnInit.bind(this);

    this._bind = () => {
        grid.data = this.data;
        grid.addEventListener("columnInit", this.onColumnInit);
        isActiveCol.bodyTemplate = this.activeTemplate;
    }
    this._bind();
}

public activeTemplate = (ctx: IgcCellTemplateContext) => {
    return html`<igc-checkbox checked="${ctx.cell.value}"></igc-checkbox>`;
}

<igc-tree-grid id="grid">
    <igc-grid-state id="gridState"></igc-grid-state>
    <igc-column id="isActive" field="IsActive" header="IsActive">
    </igc-column>
</igc-tree-grid>

constructor() {
    var grid = this.grid = document.getElementById('grid') as IgctreeGridComponent;
    var isActive = this.isActive = document.getElementById('isActive') as IgcColumnComponent;
    this.onColumnInit = this.onColumnInit.bind(this);

    this._bind = () => {
        grid.data = this.data;
        grid.addEventListener("columnInit", this.onColumnInit);
        isActive.bodyTemplate = this.activeTemplate;
    }
    this._bind();
}

public activeTemplate = (ctx: IgcCellTemplateContext) => {
    return html`<igc-checkbox checked="${ctx.cell.value}"></igc-checkbox>`;
}

<igc-hierarchical-grid id="grid">
    <igc-column id="isActive" field="IsActive" header="IsActive">
    </igc-column>
</igc-hierarchical-grid>

constructor() {
    var grid = this.grid = document.getElementById('grid') as IgcHierarchicalGridComponent;
    var isActive = this.isActive = document.getElementById('isActive') as IgcColumnComponent;
    this.onColumnInit = this.onColumnInit.bind(this);

    this._bind = () => {
        grid.data = this.data;
        grid.addEventListener("columnInit", this.onColumnInit);
        isActive.bodyTemplate = this.activeTemplate;
    }
    this._bind();
}

public activeTemplate = (ctx: IgcCellTemplateContext) => {
    return html`<igc-checkbox checked="${ctx.cell.value}"></igc-checkbox>`;
}

2 - In the ColumnInit event handler, assign the template to the column BodyTemplate property:

public onColumnInit(event: any) {
    const column = event.detail as IgcColumnComponent;
    if (column.field === 'IsActive') {
        column.bodyTemplate = this.activeTemplate;
    }
}

Demo

Limitations

• GridState.getStateAsString method uses JSON.stringify() method to convert the original objects to a JSON string. JSON.stringify() does not support Functions, thats why the GridState component will ignore the columns Formatter, Filters, Summaries, IgcGrid.sortStrategy, Column.cellClasses, CellStyles, HeaderTemplate and BodyTemplate properties.

API References

Additional Resources

• Paging
• Filtering
• Sorting
• Selection