diff --git a/blazor/datagrid/state-management.md b/blazor/datagrid/state-management.md index c4bcae9c13..789f31001a 100644 --- a/blazor/datagrid/state-management.md +++ b/blazor/datagrid/state-management.md @@ -1,7 +1,7 @@ --- layout: post title: State Management in Blazor DataGrid | Syncfusion -description: Checkout and learn here all about state management in Syncfusion Blazor DataGrid and much more details. +description: Learn how to persist, restore, and manage state in Syncfusion Blazor DataGrid, including saving, resetting, and versioned persistence. platform: Blazor control: DataGrid documentation: ug @@ -9,34 +9,34 @@ documentation: ug # State Management in Blazor DataGrid -State management in the Syncfusion® Blazor DataGrid allows you to maintain the Grid's state even after a browser refresh or when navigating to a different page within the same browser session. This feature is particularly useful for retaining the Grid's configuration and data even after a page reload. +State management in the Syncfusion® Blazor DataGrid enables preserving the grid’s configuration across browser reloads and page navigation within the same browser context. This includes settings such as paging, sorting, filtering, grouping, column visibility, and more. State persistence applies to the grid configuration, not the underlying data source; ensure the data is provided again on reload. -To enable state persistence in the Grid, you can utilize the [EnablePersistence](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnablePersistence) property. When this property is set to **true**, the Grid will automatically save its state in the browser's [LocalStorage](https://www.w3schools.com/html/html5_webstorage.asp#), ensuring that the state is preserved across page reloads. +To enable state persistence, use the [EnablePersistence](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnablePersistence) property. When set to true, the grid saves its state to the browser’s [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage), so the settings are retained across reloads until cleared. ```cs ``` -> The Grid will store the state using the combination of the component name and component ID in the storage. For example, if the component name is **Grid** and the ID is **OrderDetails**, the state will be stored as **gridOrderDetails**. +> The grid stores its state using a combination of the component name and component ID. For example, with component name Grid and ID OrderDetails, the storage key becomes gridOrderDetails. For scenarios with multiple grids on a page or versioned persistence, use the [PersistenceKey](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_PersistenceKey) property to avoid key collisions. -When enabling state persistence, the following Grid settings will persist in the local storage. +When enabling state persistence, the following grid settings are saved in local storage. -| Grid Settings | Properties persist | Ignored properties | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| PageSettings | CurrentPage
PageCount
PageSize
PageSizes | Template
EnableQueryString | -| GroupSettings | AllowReordering
Columns
DisablePageWiseAggregates
EnableLazyLoading
ShowDropArea
ShowGroupedColumn
ShowToggleButton
ShowUngroupButton | CaptionTemplate | +| Grid Settings | Properties persist | Ignored properties | +|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| PageSettings | CurrentPage
PageCount
PageSize
PageSizes | Template
EnableQueryString | +| GroupSettings | AllowReordering
Columns
DisablePageWiseAggregates
EnableLazyLoading
ShowDropArea
ShowGroupedColumn
ShowToggleButton
ShowUngroupButton | CaptionTemplate | | Columns | AllowEditing
AllowFiltering
AllowGrouping
AllowReordering
AllowResizing
AllowSearching
AllowSorting
AutoFit
DisableHtmlEncode
EnableGroupByFormat
Field
ForeignKeyField
Index
ShowColumnMenu
ShowInColumnChooser
Type
Uid
Visible
Width | ClipMode
Commands
CustomAttributes
DataSource
DefaultValue
DisplayAsCheckBox
Edit
EditTemplate
EditType
Filter
filterItemTemplate
FilterTemplate
ForeignKeyValue
Format
Freeze
HeaderTemplate
HeaderText
HeaderTextAlign
HeaderValueAccessor
HideAtMedia
IsFrozen
IsIdentity
IsPrimaryKey
MaxWidth
MinWidth
SortComparer
Template
TextAlign
ValidationRules | -| SortSettings | - | - | -| FilterSettings | - | - | -| SearchSettings | - | - | -| SelectedRowIndex | - | - | +| SortSettings | - | - | +| FilterSettings | - | - | +| SearchSettings | - | - | +| SelectedRowIndex | - | - | -The Grid will persist only the last selected row index. +Only a single selected row index is persisted. In multi-selection modes, the selection set is not stored. -N> The state will be persisted based on **ID** property. So, it is recommended to explicitly set the **ID** property for Grid. +N> State is persisted based on the ID property. Set an explicit ID or use PersistenceKey to ensure predictable behavior and to prevent key collisions. localStorage persists until cleared by application code, the user, or browser policies; it may not persist in private/incognito modes and is subject to per-origin storage limits. -The following example demonstrates how to enabling persistence in Grid: +The following example demonstrates how to enable persistence in the grid: {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -122,13 +122,11 @@ public class OrderData ## Restore initial Blazor DataGrid state -In the Syncfusion® Blazor DataGrid, you have the capability to restore the Grid to its initial state, reverting all changes and configurations made during the interaction. This feature can be particularly useful when you want to reset the Grid to its original settings, eliminating any applied filters, sorting, or column reordering. +The Syncfusion® Blazor DataGrid supports reverting to the initial configuration, clearing changes made during interaction. This is useful for resetting applied filters, sorting, grouping, column operations, and more. ### Using method -Here are the steps to reset the Syncfusion® Blazor DataGrid to its initial state, even when the [EnablePersistence](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnablePersistence) property is enabled: - -You can use [ResetPersistData](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_ResetPersistData) method to reset Grid state to its original state. This will clear persisted data in window local storage and renders Grid with its original property values. +Use the [ResetPersistData](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_ResetPersistData) method to restore the grid to its original state when persistence is enabled. This clears the persisted state in browser local storage and renders the grid with its initial property values. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -210,7 +208,7 @@ public class OrderData ### Clearing local storage -Another method to reset the Syncfusion® Blazor DataGrid is by clearing the local storage associated with the Grid. This action removes any stored state information, allowing the Grid to return to its original configuration. +Another way to reset the Syncfusion® Blazor DataGrid is by clearing the local storage used by the grid. This removes stored state information and returns the grid to its initial configuration. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -295,23 +293,15 @@ public class OrderDetails ## Restore to specific state version -The Syncfusion® Blazor DataGrid supports state persistence, allowing to save and restore Grid configurations such as column settings, filters, sorting, grouping, paging, and more. This example demonstrates how to implement version-based state persistence using localStorage. - -In this sample, each version represents a unique saved Grid configuration (or state). When a version button is clicked: - -1. The current Grid state is saved to localStorage using the existing version key. - -2. The Grid switches to the selected version. +The Syncfusion® Blazor DataGrid supports state persistence and can save and restore configurations such as column settings, filters, sorting, grouping, and paging. This example demonstrates version-based state persistence using local storage, where each version corresponds to a unique saved configuration. -3. If persisted data exists for the selected version, it is applied to the Grid. +When a version is selected: +1. The current grid state is saved to local storage under the active version key. +2. The grid switches to the selected version. +3. If persisted data exists for the selected version, it is applied to the grid. +4. If no data exists, a new state will be stored the next time the grid changes. -4. If no data is found, a new state will be stored the next time the Grid is modified. - -To implement version-based persistence in Grid, set **PersistenceKey** dynamically based on the selected version (e.g., gridOrderDetails_v.1), ensuring each version maintains a unique state in localStorage. The core logic for switching versions is handled in the `ChangeVersion` method. - -* This method saves the current Grid state using [GetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetPersistDataAsync) before switching versions. The `GetPersistDataAsync` method returns the Grid’s current state as a string, which is suitable for sending over a network or storing in databases. - -* It then attempts to load the state associated with the selected version using [SetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_SetPersistDataAsync_System_String_). If a persisted state is available, it is applied to the Grid. Otherwise, a message is displayed indicating that no saved state exists and a new state will be stored going forward. +To implement version-based persistence, set the PersistenceKey dynamically based on the selected version (for example, gridOrderDetails_v.1) so each version maintains a distinct state in local storage. The ChangeVersion method coordinates saving the current state using [GetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetPersistDataAsync) and then applies the selected version via [SetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_SetPersistDataAsync_System_String_). {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -426,11 +416,9 @@ public class OrderDetails ## Restore to previous state -The Syncfusion® Blazor DataGrid allows you to save and restore its state using local storage. This feature is helpful when you want to preserve the current state of the Grid, such as column order, sorting, and filtering, so that you can return to your previous work or configurations. - -To implement this functionality, use the `getItem` and `setItem` methods for local storage, along with the Grid's [GetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetPersistDataAsync) and [SetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_SetPersistDataAsync_System_String_) methods. The `GetPersistDataAsync` method retrieves the current Grid state as a string, which can be saved in local storage. The `SetPersistDataAsync` method restores the saved Grid state from local storage. +The Syncfusion® Blazor DataGrid can save and restore its current state using local storage. This preserves configuration such as column order, sorting, filtering, and more, allowing a return to a previous configuration. -The provided code demonstrates how to save and restore the previous state of a Grid using local storage. +Use the browser’s getItem and setItem methods with the grid’s [GetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetPersistDataAsync) and [SetPersistDataAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_SetPersistDataAsync_System_String_) methods. GetPersistDataAsync returns the grid state as a string suitable for storage; SetPersistDataAsync applies the saved state. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -453,7 +441,7 @@ The provided code demonstrates how to save and restore the previous state of a G - + @@ -552,7 +540,7 @@ public class OrderDetails ## Maintaining custom query in a persistent state -When [EnablePersistence](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnablePersistence) is enabled, the Syncfusion® Blazor DataGrid does not automatically maintain custom query parameters after a page load. This is because the Grid refreshes its query params for every page load. You can maintain the custom query params by resetting the `AddParams` method in the [OnActionBegin](https://blazor.syncfusion.com/documentation/datagrid/events#onactionbegin) event. +When [EnablePersistence](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnablePersistence) is enabled, the Syncfusion® Blazor DataGrid does not automatically maintain custom query parameters after a page load because the grid refreshes its query parameters on each load. To retain custom parameters, reset the AddParams call in the [OnActionBegin](https://blazor.syncfusion.com/documentation/datagrid/events#onactionbegin) event. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -628,9 +616,9 @@ public class OrderDetails ## Get or set local storage value -If the [EnablePersistence](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnablePersistence) property is set to **true**, the Syncfusion® Blazor DataGrid property value is saved in the **window.localStorage** for reference. You can get or set the localStorage value by using the **getItem** and **setItem** methods in **window.localStorage**. +If the [EnablePersistence](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnablePersistence) property is set to true, the Syncfusion® Blazor DataGrid property values are saved in window.localStorage. Use getItem and setItem on window.localStorage to retrieve or update the stored model. -To retrieve the Grid model from Local Storage, follow these steps: +To retrieve the grid model from local storage: ```cs string localStorageKey = "gridOrders"; //"gridOrders" is component name + component id. @@ -642,4 +630,4 @@ var modelObject = JsonSerializer.Deserialize(modelJson); await JS.InvokeVoidAsync("localStorage.setItem", localStorageKey, modelJson); ``` -N> You can refer to our [Blazor DataGrid](https://www.syncfusion.com/blazor-components/blazor-datagrid) feature tour page for its groundbreaking feature representations. You can also explore our [Blazor DataGrid example](https://blazor.syncfusion.com/demos/datagrid/overview?theme=bootstrap5) to understand how to present and manipulate data. \ No newline at end of file +N> Refer to the [Blazor DataGrid](https://www.syncfusion.com/blazor-components/blazor-datagrid) feature tour page for feature highlights. Explore the [Blazor DataGrid example](https://blazor.syncfusion.com/demos/datagrid/overview?theme=bootstrap5) to see how to present and manipulate data. \ No newline at end of file