Blazor Hierarchical Grid State Persistence
The Ignite UI for Blazor State Persistence in Blazor Hierarchical Grid allows developers to easily save and restore the grid state. When the IgbGridState
is applied on the Blazor IgbHierarchicalGrid
, it exposes the GetStateAsStringAsync
and ApplyStateFromStringAsync
methods that developers can use to achieve state persistence in any scenario.
Supported Features
IgbGridState
directive supports saving and restoring the state of the following features:
- RowIslands
- saving/restoring features for all child grids down the hierarchy
- Sorting
- Filtering
- AdvancedFiltering
- Paging
- CellSelection
- RowSelection
- ColumnSelection
- RowPinning
- Expansion
- Columns
- Multi column headers
- Columns order
- Column properties defined by the
IColumnState
interface.
Usage
The GetStateAsStringAsync
returns a serialized JSON string, so developers can just take it and save it on any data storage (database, cloud, browser localStorage, etc).
The developer may choose to get only the state for a certain feature/features, by passing in an array with feature names as an argument. Empty array will result to using the default state options.
<IgbHierarchicalGrid>
<IgbGridState @ref="gridState"></IgbGridState>
</IgbHierarchicalGrid>
@code {
// get all features` state in a serialized JSON string
string stateString = gridState.GetStateAsStringAsync(new string[0]);
// get the sorting and filtering expressions
string sortingFilteringStates = gridState.GetStateAsStringAsync(new string[] { "sorting", "filtering" });
}
ApplyStateFromStringAsync
- The method accepts a serialized JSON string as argument and will restore the state of each feature found in the JSON string or specified features as second argument.
gridState.ApplyStateFromStringAsync(gridStateString, new string[0]);
gridState.ApplyStateFromStringAsync(sortingFilteringStates, new string[0])
The Options
object implements the IgbGridStateOptions
interface, i.e. for every key, which is the name of a certain feature, there is the boolean value indicating if this feature state will be tracked. GetStateAsStringAsync
methods will not put the state of these features in the returned value and ApplyStateFromStringAsync
methods will not restore state for them.
gridState.Options = new IgbGridStateOptions
{
CellSelection = false,
Sorting = false
};
The simple to use single-point API's allows to achieve a full state persistence functionality in just a few lines of code. Copy paste the code from below - it will save the grid state in the browser LocalStorage
object every time the user leaves the current page. Whenever the user returns to main page, the grid state will be restored. No more need to configure those complex advanced filtering and sorting expressions every time to get the data you want - do it once and have the code from below do the rest for your users:
@using IgniteUI.Blazor.Controls
@using Newtonsoft.Json
@implements IDisposable
@inject IJSRuntime JS
@inject NavigationManager Navigation
<IgbHierarchicalGrid Rendered="OnGridRendered">
<IgbGridState @ref="gridState"></IgbGridState>
<IgbColumn Field="ContactName" Header="Name" MinWidth="200px" ></IgbColumn>
<IgbColumn Field="ContactTitle" Header="Title" MinWidth="200px" Sortable="true" Filterable="true" Groupable="true"></IgbColumn>
<IgbColumn Field="CompanyName" Header="Company" MinWidth="200px" Sortable="true" Filterable="true" Groupable="true"></IgbColumn>
</IgbHierarchicalGrid>
@code {
protected override void OnAfterRender(bool firstRender)
{
Navigation.LocationChanged += OnLocationChanged;
}
void OnLocationChanged(object sender, LocationChangedEventArgs e)
{
SaveGridState();
}
void IDisposable.Dispose()
{
// Unsubscribe from the event when our component is disposed
Navigation.LocationChanged -= OnLocationChanged;
}
void OnGridRendered()
{
RestoreGridState();
}
async void SaveGridState() {
string state = gridState.GetStateAsStringAsync(new string[0]);
await JS.InvokeVoidAsync("window.localStorage.setItem", "grid-state", state);
}
async void RestoreGridState() {
string state = await JS.InvokeAsync<string>("window.localStorage.getItem", "grid-state");
if (state) {
gridState.ApplyStateFromStringAsync(state, new string[0]);
}
}
}
Restoring Child Grids
Saving / Restoring state for the child grids is controlled by the RowIslands
property and is enabled by default. IgbGridState
will use the same options for saving/restoring features both for the root grid and all child grids down the hierarchy. For example, if we pass the following options:
<IgbHierarchicalGrid>
<IgbGridState @ref="gridState"></IgbGridState>
</IgbHierarchicalGrid>
@code {
private IgbGridState gridState;
gridState.Options = new IgbGridStateOptions
{
CellSelection = false,
Sorting = false,
RowIslands = true
};
}
Then the GetState
API will return the state for all grids (root grid and child grids) features excluding Selection
and Sorting
. If later on the developer wants to restore only the Filtering
state for all grids, use:
gridState.ApplyStateFromStringAsync(gridStateString, new string[] { "filtering", "rowIslands" });
Demo
Limitations
- When restoring all grid features at once (using
applyState
API with no parameters), then column properties for the root grid might be resetted to default. If this happens, restore the columns or column selection feature separately after that:
GetStateAsString
method uses JSON.stringify() method to convert the original objects to a JSON string. JSON.stringify() does not support Functions, thats why theIgbGridState
component will ignore the columnsFormatter
,Filters
,Summaries
,SortStrategy
,CellClasses
,CellStyles
,HeaderTemplate
andBodyTemplate
properties.