Grid State Persistence

Revision history

Version	User	Date	Notes
0.1	Hristo Anastasov	06.11.2019	Specification for State Persistence directive and API

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. For example the user navigates back to a page running a grid on it, the user wants to see the filtering and sorting expressions configured during last page visit applied initially.

2. User Stories

Developer:

• Story 1: As a citizen developer, I want to choose which feature is saved/restored by the IgxGridState directive.
• Story 2. As a citizen developer, I want to reset the grid state as if the IgxGridState directive was not applied.
• Story 3. As a citizen developer, I want to get a feature state on API call.
• Story 4. As a citizen developer, I want to get the columns state on API call.
• Story 5. As a citizen developer, I want to restore the feature/columns state on API call.
• Story 6. As a citizen developer, I want to restore the columns state or certain feature state on API call.

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.
• Story 2: As an end user, I want to select what features to restore their state from last session, when I execure the corresponding (button click).
• Story 3: As an end user, I want to save different presets for features, i.e. presets for advanced filtering, give those resets names and restore them on action.

Acceptance criteria

1. After applying the IgxGridState directive on the grid with default values, the grid restores its:

• sorting expressions
• filtering expressions
• columns state (pinned, sortable, filterable, movable, hidden, summary, hasSummary, width, header)
• selection state
• group-by state
• paging state

2. The developer is able to get the current state of the grid thorugh the gridAPI, even if the IgxGridState directive is not applied.

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 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;
    excelStyleFiltering?: boolean;
    paging?: boolean;
    sorting?: boolean;
    columns?: boolean;
}

Every key/value pair in the IGridStateOptions indicates if a certain feature state will be saved/restored. The directive is handling everything out of the box for the dev, using the sessionStorage object.

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

If the IgxGridState directive is not applied at all, the developer can implement saving/restoring state on his own, choosing a storage object by preferences. The deeloper can retrieve the grid state (containing all features and columns state), or the state per gien feature via an API call:

const sortingState = this.grid.gridAPI.getSortingState();
// save sortingState

And then restore the state in the AfterViewInit lifecycle, or later:

public ngAfterViewInit() {
    this.grid.gridAPI.restoreSortingState(sortingState);
    // this.grid.gridAPI.restoreState(gridState);
    // this.gridAPI.restoreColumnsState(columnsState);
    this.grid.cdr.detectChanges();
}

3.3. Globalization/Localization

N/A

3.4. User Interface

N/A

3.5. API

Options

Name	Description	Type	Default value	Valid values
IgxState	State directive to be applied on the grid	n/a	n/a	n/a
options	Object containing the features which state to be saved/restored	object	IGridStateOptions

Methods

Name	Description	Return type	Parameters
getState(params)	Returns the current grid state. If IgxState directive is applied, this equals the last stored state.	IGridState	featureName: string[]
getSortingState()	Returns the current sorting state. If IgxState directive is applied, this equals the last stored state.	ISortingState
getSelectionState()	Returns the current selection state. If IgxState directive is applied, this equals the last stored state.	ISelectionState
getFilteringState()	Returns the current filtering state. If IgxState directive is applied, this equals the last stored state.	IFilteringState
getPagingState()	Returns the current paging state. If IgxState directive is applied, this equals the last stored state.	IPagingState
getColumnsState()	Returns the current columns state. If IgxState directive is applied, this equals the last stored state.	IColumnState	columnName: string[]
setState(gridState)	Restores the grid state from an IGridState object.	IGridState	IGridState
setSortingState(sortingState, false)	Apply sorting expressions from ISortingState object.	ISortingState	ISortingState, fireEvents: bool
setFilteringState(filteringState, true)	Apply filtering expressions from IFilteringState object.	IFilteringState	IFilteringState, fireEvents: bool
setPagingState(pagingState, false)	Enable paging, sets page size and chage page index based on IPagingState object	IPagingState	IPagingState, fireEvents: bool
setSelectionState(selectionState, false)	Select rows/cells based on ISelectionState object	ISelectionState	ISelectionState, fireEvents: bool
setColumnsState(columnsState, false)	Set pinned state, hidden state, width, sortable, filterable, movable, hasSummary, summaries and header properties for the columns currently in the grid.	IColumnState	IColumnState, fireEvents: bool

Events

N/A

4. ARIA Support

N/A

5. Assumptions and Limitations

Assumptions	Limitation Notes
It makes sense to page the filtered data set(if filtering has bee applied).	When restoring paging, filtering is also restored. Cannot restore paging without resoring filtering.
Not sure if will be able to supress events fired on restoring.

6. References

N/A