Managing the Angular Data Grid State
The Grid provides built-in state management functionality that allows you to save and restore the state across sessions.
This is particularly useful in scenarios where you may navigate away from the Grid or refresh the page, and you want to ensure that your preferences are preserved. For example, if you are working with a large dataset and have applied specific filters, sorting, or grouping, you can return to the same view without having to reapply all the settings.
The following example demonstrates the state persistence feature of the Grid where the settings are saved in the local storage.
You can persist the following data operations and column settings of the Grid:
Feature | Description |
---|---|
Sorting | Shows the data in the same order, so users don’t need to sort again. |
Filtering | Keeps filters in place, so users always see the data they care about. |
Grouping | Remembers how data was grouped to make it easy to understand again. |
Paging | Opens the same page the user was last on, saving time. |
Column Visibility | Hides or shows the same columns the user picked before. |
Columns Order | Keeps the columns in the same order the user arranged them. |
Columns Width | Keeps the same column sizes for easy reading. |
Sticky Columns | Keeps the sticky state of the columns |
Locked Columns | Keeps important columns in view. |
Saving the Grid State
The Grid automatically saves the settings in the currentState
field when binding data through the kendoGridBinding
directive.
The currentState
is updated whenever the Grid's configuration changes. Such changes include data operations like sorting, filtering, grouping, and paging, as well as column settings like resizing, reordering, and hiding/showing columns.
The following code snippet demonstrates how to access the current state of the Grid and save it to local storage.
public saveState(grid: GridComponent): void {
const gridState: GridState = grid.currentState;
localStorage.setItem("grid-state", JSON.stringify(state));
}
Saving the Grid State with data
Binding
When using the data
property to bind the Grid, you need to manually save the current state. This is done by handling the gridStateChange
event which is emitted whenever the Grid's configuration changes.
<kendo-grid (gridStateChange)="onStateChange($event)" ...>
...
</kendo-grid>
The event handler receives a GridState
object as an argument, which contains the current Grid settings. You can use this object to save the state to local storage or any other storage mechanism of your choice.
public currentState: GridState;
public onStateChange(state: GridState): void {
this.currentState = state
}
public saveState(): void {
localStorage.setItem("grid-state", JSON.stringify(this.currentState));
}
Restoring the Grid State
You can reload the saved preferences using the loadState
method of the Grid. The method accepts the GridState
object as an argument and applies the saved configuration, ensuring the Grid looks exactly as it was left.
The following code snippet demonstrates how to restore the Grid state from local storage.
@ViewChild(GridComponent) grid: GridComponent;
public restoreGridState(): void {
const state: GridState = JSON.parse(localStorage.getItem("grid-state"));
this.grid.loadState(state);
}
Restoring the Grid State with data
Binding
When using data
binding to bind the Grid, you need to manually apply the data operations state to the data source, using the process
method from the Data Query package. More details can be found in the Handling Data Operations article.
public state: GridState;
public restoreGridState(){
this.gridData = process(products, {
sort: this.state.sort,
filter: this.state.filter,
group: this.state.group,
});
}
Undo and Redo the Grid State
With the undo and redo functionality, you can easily revert or reapply changes made to the Grid's configuration.
This feature is especially useful when you want to experiment with different settings, such as sorting, filtering, or grouping, without worrying about losing your previous configurations. By enabling undo and redo, you can seamlessly navigate between states, improving your workflow and productivity.
The Grid provides multiple options to enable Undo and Redo functionality, including built-in tools, a customizable history stack, and programmatic methods for advanced use cases. The following sections outline these options in detail.
Built-in Undo and Redo
The Grid provides built-in undo and redo toolbar tools, allows you to easily revert or reapply previous states.
The following example demonstrates the undo and redo functionality of the Grid.
To enable the undo and redo buttons functionality:
-
Apply the
kendoGridUndoRedo
directive to the Grid. -
Add the Undo and Redo toolbar button tools and apply the
kendoGridUndoTool
andkendoGridRedoTool
directives to them.html<kendo-grid kendoGridUndoRedo> <kendo-toolbar> <kendo-toolbar-button kendoGridUndoTool></button> <kendo-toolbar-button kendoGridRedoTool></button> </kendo-toolbar> </kendo-grid>
History Stack
The undo and redo functionality uses a history stack to manage the Grid's state. Each configuration change (e.g., sorting, filtering, grouping) pushes the current state onto the stack. Clicking Undo reverts to the last state by popping it from the stack, while Redo reapplies a previously undone state by pushing it back onto the stack.
You can customize the number of states stored in the history stack by setting the maxStoredStates
property. By default, the Grid stores up to 10 states in the history stack, but you can adjust this value to suit your application's needs.
<kendo-grid kendoGridUndoRedo [maxStoredStates]="40" ...>
<kendo-grid-toolbar>
<button kendoButton kendoGridUndoTool>Undo</button>
<button kendoButton kendoGridRedoTool>Redo</button>
</kendo-grid-toolbar>
</kendo-grid>
Custom Undo and Redo
To provide your own undo and redo buttons or implement a more complex undo/redo functionality, you can use the undo
and redo
methods of the kendoGridUndoRedo
directive. This directive provides access to the underlying undo and redo functionality of the Grid, allowing you to further customize the behavior.
-
Apply the
kendoGridUndoRedo
directive to the Grid and reference its instance using a template variable. In the following code snippet, the template variable is namedundoRedo
.html<kendo-grid kendoGridUndoRedo #undoRedo="kendoGridUndoRedo" ...></kendo-grid>
-
Use the instance from the first step to call the
undo
andredo
methods and revert or reapply changes to the Grid's configuration.html<button kendoButton (click)="undoRedo.undo()">Undo</button> <button kendoButton (click)="undoRedo.redo()">Redo</button>
Known Limitations
- The built-in state management APIs - the
currentState
getter, thegridStateChange
event, and the undo/redo functionality rely on cloning the current Grid data. If any data item has a property that points to a function, cloning the object will trigger a JavaScript error.