Grid State Persistence

Revision history

Version	User	Date	Notes
0.1	Hristo Anastasov	06.11.2019	Specification for State Persistence directive and API
0.2	Hristo Anastasov	06.11.2019	Specification for State Persistence directive and API
0.3	Hristo Anastasov	06.11.2019	Final version of API exposed.
0.4	Hristo Anastasov	19.11.2019	Refining return type and parameters of public methods.
0.5	Hristo Anastasov	28.05.2020	Add support for igxHierarchicalGrid and igxTreeGrid, support for expansion states
0.6	Maya Kirova	18.07.2022	Add support for igxPivotGrid by storing the pivotConfiguration

• Radoslav Mirchev | Date:
• Konstantin Dinev | Date:

Grid State Persistence Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. API
5. Assumptions and Limitations
6. Angular elements implementation

Objectives

The Grid State Persistence feature aims at providing an easy out-of-the-box way for developers to save/and restore the state of the IgxGrid, IgxTreeGrid, IgxHierarchicalGrid and the igxPivotGrid. Once the IgxGridState directive is applied, the developer will be able to get the current state of a feature or all features using getState method, and later apply it on the grid using setState method (see API).

2. User Stories

Developer:

• Story 1. As a citizen developer, I want to get the grid state on API call.
• Story 2. As a citizen developer, I want to pass an options object describing what features state are not needed to be saved.
• Story 2. As a citizen developer, I want to get only the columns state or certain feature state on API call.
• Story 3. As a citizen developer, I want to restore the state by passing in the state object retrieved by the getState method as an argument to the setState method.

End user:

• Story 1: As an end user, I want to see the same grid state as I left it on my last visit of the page.

Acceptance criteria

1. After applying the IgxGridState directive on the grid, calling getState method on the directive will return a serialized object implementing the IGridState, (ITreeGridState, IHierarchicalGridState yet to be aded) interface, containing:

• sorting expressions
• groupby expressions (only available for igxGrid)
• filtering expressions
• columns state (pinned, sortable, filterable, movable, hidden, summary, hasSummary, width, header) implementing the IColumnState interface:

interface IColumnState {
    field: string;
    header?: string;
    width?: string;
    dataType?: string;
    pinned?: boolean;
    sortable?: boolean;
    filterable?: boolean;
    movable?: true;
    hidden?: boolean;
}

• selection state
• paging state
• row pinning (only available for igxGrid)
• expansion states
• row islands state (only for IgxHierarchicalGrid), implementing the IGridStateCollection interface: export interface IGridStateCollection { id: string; state: IGridState; }
• pivot configuration state (only available for igxPivotGrid).

2. After applying the IgxGridState directive, calling getState with a false argument will return a non-serialized object implementing the IGridState, (ITreeGridState, IHierarchicalGridState yet to be added) interface.

3. Functionality

3.1. End User Experience The user experience is the same as user has applied sorting, filtering, etc, through the UI.

3.2. Developer Experience The developer is applying the IgxGridState directive on the grid, which allows working with the State Persistence API to easily retrieve/set the grid state.

Based on the use case, the developer may choose to apply the IgxGridState directive along with an optional options object implementing the IGridStateOptions interface:

interface IGridStateOptions {
    selection?: boolean;
    filtering?: boolean;
    advancedFiltering?: boolean;
    paging?: boolean;
    sorting?: boolean;
    groupby? : boolean;
    columns?: boolean;
    rowPinning?: Boolean;
    expansion? : Boolean;
    rowIslands? : boolean;
    pivotConfiguration?: IPivotConfiguration;
}

<igx-grid #grid [igxGridState]="options" [data]="localData" ></igx-grid>

@ViewChild(IgxGridStateDirective, { static: true }) public state;
public options = {
    selection: false,
    filtering: true,
    advancedFiltering: false,
    paging: true,
    sorting: true,
    groupby: false,
    columns: true
};

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

    this.restoreGridState();
  }

  public saveGridState() {
    const state = this.state.getState();
    // save `state` object to any database, localStorage, etc.
  }

  public restoreGridState() {
      // retrieve `state` from the data storage
      this.state.setState(state);
  }

Every key/value pair in the IGridStateOptions indicates if a certain feature state will be saved/restored.

3.3. Globalization/Localization

N/A

3.4. User Interface

N/A

3.5. API

Options

Name	Description	Type	Default value	Valid values
options	Object containing the features which state to be saved/restored	object	IGridStateOptions

private _options: IGridStateOptions = {
    columns: true,
    filtering: true,
    advancedFiltering: true,
    sorting: true,
    groupby: true,
    paging: true,
    selection: true,
    pivotConfiguration: true
};

Methods

Name	Description	Return type	Parameters
getState(params)	Returns the current grid state in a serialized object, when called without arguments. Can be called with parameters to return the state only for a particular feature. Calling with a false serialize argument will return a non-serialized object.	IGridState, string	feature: string, string[], serialize: boolean
setState(gridState)	Restores the grid state or a certain feature state from a state object, either serialized or non-serialized.	void	object: IGridState

Events

N/A

4. ARIA Support

N/A

5. Assumptions and Limitations

Assumptions	Limitation Notes
Filtering depends on knowing the column data types. If Filtering is enabled, columns are enabled too.
In case the state is stored and applied as string, custom functions and templates applied to any of the stored objects will not be restored out of the box. This includes, but is not limited to: - igxColumn functions and temples - fomatter, filters, summaries etc. - Pivot Dimension and Value functions - memberFunction, formatter, styles, custom aggregator functions etc.	For such scenarios, the functions/templates need to be manually applied on the related initialization events - columnInit, dimensionInit, valueInit etc.

6. References

N/A

7. Angular elements implementation

For the web components version of the grids, we've added an igc-grid-state component, which extends the existing directive's functionality.

Note: The component is not part of Angular's public API. It exist only for the web component version as a way to declaratively add the functionality to the web component's grid, since angular elements cannot wrap directives.

It can be declaratively added to any of the grid components as a child:

<igc-grid ...>
    <igc-grid-state id="state"></igc-grid-state>
</igx-grid>

And exposes the same API as the directive.