Angular Hierarchical Grid State Persistence

    Тhe igxGridState directive allows developers to easily save and restore the grid state. When the IgxGridState directive is applied on the grid, it exposes the getState and setState methods that developers can use to achieve state persistence in any scenario.

    Supported Features

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

    • RowIslands
      • saving/restoring features for all child grids down the hierarchy
    • Sorting
    • Filtering
    • Advanced Filtering
    • Paging
    • Cell Selection
    • Row Selection
    • Column Selection
    • Row Pinning
    • Expansion
    • Columns
      • NEW: Multi column headers are now supported out of the box
      • Columns order
      • Column properties defined by the IColumnState interface.
      • Columns templates and functions are restored using application level code, see Restoring Column section.
    Note

    The IgxGridState directive does not take care of templates. Go to Restoring Column section to see how to restore column templates.

    Usage

    getState - This method returns the grid state in a serialized JSON string, so developers can just take it and save it on any data storage (database, cloud, browser localStorage, etc). The method accepts first optional parameter serialize, which determines whether getState will return an IGridState object or a serialized JSON string. The developer may choose to get only the state for a certain feature/features, by passing in the feature name, or an array with feature names as a second argument.

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

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

// get the sorting and filtering expressions
const sortingFilteringStates: IGridState = state.getState(false, ['sorting', 'filtering']);

    setState - The setState method accepts the serialized JSON string or IGridState object as argument and will restore the state of each feature found in the object/JSON string.

    state.setState(gridState);
state.setState(sortingFilteringStates)

    options - The options object implements the IGridStateOptions 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 method will not put the state of these features in the returned value and setState method will not restore state for it.

    public options =  { cellSelection: false; sorting: false; }

    <igx-hierarchical-grid [igxGridState]="options"></igx-hierarchical-grid>

    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 sessionStorage 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:

    // app.component.ts
@ViewChild(IgxGridStateDirective, { static: true })
public state!: IgxGridStateDirective;

public ngOnInit() {
    this.router.events.pipe(take(1)).subscribe((event: NavigationStart) => {
        this.saveGridState();
    });
}

public ngAfterViewInit() {
    this.restoreGridState();
}

public saveGridState() {
    const state = this.state.getState() as string;
    window.sessionStorage.setItem('grid1-state', state);
}

public restoreGridState() {
    const state = window.sessionStorage.getItem('grid1-state');
    this.state.setState(state);
}

    Restoring columns

    IgxGridState 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:
    <igx-hierarchical-grid id="grid" #grid igxGridState (columnInit)="onColumnInit($event)">
    <igx-column [field]="'IsActive'" header="IsActive">
        <ng-template igxCell #activeTemplate let-column let-val="val">
            <igx-checkbox [checked]="val"></igx-checkbox>
        </ng-template>
    </igx-column>
    ...
</igx-hierarchical-grid>
    1. Query the template view in the component using @ViewChild or @ViewChildren decorator. In the columnInit event handler, assign the template to the column bodyTemplate property:
    @ViewChild('activeTemplate', { static: true }) public activeTemplate: TemplateRef<any>;
public onColumnInit(column: IgxColumnComponent) {
    if (column.field === 'IsActive') {
        column.bodyTemplate = this.activeTemplate;
        column.summaries = MySummary;
        column.filters = IgxNumberFilteringOperand.instance();
    }
}

    Restoring Child Grids

    Saving / Restoring state for the child grids is controlled by the rowIslands property and is enabled by default. IgxGridState will use the same options for saving/restoring features both for the root grid and all child grids down the hierarchy. For example, if we pass the following options:

    <!-- public options = {selection: false, sorting: false, rowIslands: true} -->
<igx-grid [igxGridState]="options"></igx-grid>

    Then the getState API will return the state for all grids (root grid and child grids) features excluding selection and sorting. If later on the developer wants to restore only the filtering state for all grids, use:

    this.state.setState(state, ['filtering', 'rowIslands']);

    Demo

    Limitations

    • When restoring all grid features at once (using setState API with no parameters), then column properties for the root grid might be resetted to default. If this happens, restore the columns or column selection feature separately after that:
    state.setState(gridState);
state.setState(gridState.columns);
state.setState(gridState.columnSelection);

    API References

    Additional Resources