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.

Grid State Persistence Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. API
5. Assumptions and Limitations

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 and IgxHierarchicalGrid. 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 interface, containing:

• sorting expressions
• groupby expressions
• 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

2. After applying the IgxGridState directive, calling getState with a false argument will return a non-serialized object implementing the IGridState, ITreeGridState, IHierarchicalGridState 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;
}

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

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	featureName: 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, IColumnState[], IFilteringExpressionsTree, ISortingExpression, IGroupingExpression, IPagingState

Events

N/A

4. ARIA Support

N/A

5. Assumptions and Limitations

N/A

6. References

N/A