Save and Restore Layout
- 8 minutes to read
The Pivot Grid allows you to save the information on its layout, and then restore it. This information includes all the settings that control the visibility and size of visual elements, their appearance settings, filtering, sorting, etc.
Basics
ASPxPivotGrid exposes the following methods that allow you to save the pivot grid layout to a stream or string:
Saves the pivot grid layout to the specified stream, using the specified settings. | |
Saves the pivot grid layout to the specified string. |
To restore the previously saved layout, use the following methods:
Restores the pivot grid layout from the specified stream, using the specified settings. | |
Restores the pivot grid layout from the specified string, using the specified settings. |
Note
To allow the pivot grid’s layout to be correctly saved and restored, ensure that unique names are specified for all pivot grid fields. Use the PivotGridField.ID property to provide a unique name for a field.
Layout Options
Each of the SaveLayoutTo… and LoadLayoutFrom… methods has two overloads - with and without the options parameter of the PivotGridWebOptionsLayout type.
When calling the SaveLayoutTo… and LoadLayoutFrom… methods without the options parameter, only a subset of the control’s settings is saved/restored. By default, these settings include:
- visibility state, position and size of fields;
- sorting and grouping settings;
- current filters;
- summary information;
- all the settings grouped within the control’s ASPxPivotGrid.OptionsView object.
Appearance, data-aware, behavior, customization, and other specific options are not saved/restored by default.
ASPxPivotGrid allows you to specify which options should be saved/restored. To do this, use the ASPxPivotGrid.OptionsLayout property, which provides the following options:
Gets or sets whether all the control’s settings (except for the appearance settings and format rules) are stored when the layout is saved to storage and restored when the layout is restored from storage. | |
Gets or sets whether the control’s appearance settings are also stored when the layout is saved to storage and restored when the layout is restored from storage. | |
Gets or sets whether the control client-side event handlers are stored when the layout is saved to a storage, and restored when the layout is restored from a storage. | |
Gets or sets whether the control’s grouping, sorting, filtering settings and summaries are stored when the layout is saved to storage and restored when the layout is restored from storage. | |
Gets or sets whether the control’s visual options are stored when the layout is saved to storage and restored when the layout is restored from storage. | |
Gets or sets whether to retain field groups that exist in the current control layout, but do not exist in the layout being restored. | |
Contains options that specify how the columns’ and bands’ settings are stored to and restored from storage (a stream, xml file or sysytem registry). |
Options exposed by the OptionsLayoutGrid.Columns property are listed below.
Gets or sets whether the columns that exist in the current control but do not exist in a layout when it’s restored should be retained. | |
Gets or sets whether the columns that exist in a layout when it’s restored but that don’t exist in the current control should be discarded or added to the control. | |
Gets or sets whether the position, width and visibility of the columns and bands are stored when the layout is saved to storage and restored when the layout is restored from storage. | |
Gets or sets whether the appearance settings of the columns and bands are also stored when the layout is saved to storage and restored when the layout is restored from storage. | |
Gets or sets whether all the settings of a control’s columns/bands (except for the appearance settings) are stored when the layout is saved to storage and restored when the layout is restored from storage. |
Another approach to specify which options need to be saved/restored is to use the SaveLayoutTo… and LoadLayoutFrom… methods with the options parameter. You can create an instance of the PivotGridWebOptionsLayout class, customize it, and pass it as the options parameter. Only options that are enabled in this object will be saved/restored. Specific options that are disabled in the options parameter are not affected. To save all layout options (without appearance, data and client-side events settings), pass null (Nothing in Visual Basic) or the static PivotGridWebOptionsLayout.FullLayout property as the options parameter.
Upgrading Layout
The ASPxPivotGrid allows you to control the upgrading of a layout while it is being loaded from a data store (a stream or string).
You can control the upgrading of the ASPxPivotGrid layout by handling the ASPxPivotGrid.LayoutUpgrade event. The event occurs when a layout is restored from a data store (by using the ASPxPivotGrid.LoadLayoutFromStream or ASPxPivotGrid.LoadLayoutFromString method), and its version differs from the version of the current ASPxPivotGrid layout.
The layout version is specified via the OptionsLayoutBase.LayoutVersion property.
You need to assign this property to distinguish between the versions of stored layouts and the current ASPxPivotGrid layout. If the versions do not match, you can customize the control to prevent the current layout from being overwritten.
Use the LayoutUpgradeEventArgs.PreviousVersion property to get the version of the layout being restored. Depending on the result, you can implement the required routine that will upgrade the old layout.
You can also control the upgrading of the ASPxPivotGrid layout by handling the ASPxPivotGrid.BeforeLoadLayout event. Handling this event allows you to prevent the layout from being restored from storage (by using the ASPxPivotGrid.LoadLayoutFromStream or ASPxPivotGrid.LoadLayoutFromString method) and from being applied to the current control. To stop the layout from being restored, set the event parameter LayoutAllowEventArgs.Allow property to false.
Use the LayoutUpgradeEventArgs.PreviousVersion property to get the version of the layout being restored.
This can be compared with the version of the current layout specified by the OptionsLayoutBase.LayoutVersion property. If the versions do not match, the layout restoration may be canceled.
Example: How to Save and Restore Layout
The following example shows how to save a pivot grid's layout to a string and then restore it.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/how-to-save-and-restore-layout-e1879
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs"
Inherits="SaveAndRestoreLayout._Default" %>
<%@ Register Assembly="DevExpress.Web.ASPxPivotGrid.v11.1, Version=11.1.4.0,
Culture=neutral, PublicKeyToken=b88d1754d700e49a"
Namespace="DevExpress.Web.ASPxPivotGrid"
TagPrefix="dx" %>
<%@ Register assembly="DevExpress.Web.ASPxEditors.v11.1, Version=11.1.4.0,
Culture=neutral, PublicKeyToken=b88d1754d700e49a"
namespace="DevExpress.Web.ASPxEditors"
tagprefix="dx" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Save and Restore Layout Example</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<dx:ASPxPivotGrid ID="ASPxPivotGrid1" runat="server"
DataSourceID="AccessDataSource1">
<Fields>
<dx:PivotGridField ID="fieldCity" Area="ColumnArea"
AreaIndex="2" FieldName="City">
</dx:PivotGridField>
<dx:PivotGridField ID="fieldRegion" Area="ColumnArea"
AreaIndex="1" FieldName="Region">
</dx:PivotGridField>
<dx:PivotGridField ID="fieldCountry" Area="ColumnArea"
AreaIndex="0" FieldName="Country">
</dx:PivotGridField>
<dx:PivotGridField ID="fieldQuantity" Area="DataArea"
AreaIndex="0" FieldName="Quantity">
</dx:PivotGridField>
<dx:PivotGridField ID="fieldUnitPrice" Area="DataArea"
AreaIndex="1" FieldName="UnitPrice">
</dx:PivotGridField>
<dx:PivotGridField ID="fieldProductName" Area="RowArea"
AreaIndex="0" FieldName="ProductName">
</dx:PivotGridField>
</Fields>
</dx:ASPxPivotGrid>
<asp:AccessDataSource ID="AccessDataSource1" runat="server"
DataFile="~/App_Data/nwind.mdb"
SelectCommand="SELECT [City], [Region], [Country],
[Quantity], [UnitPrice], [ProductName]
FROM [Invoices]">
</asp:AccessDataSource>
</div>
<div>
<table cellspacing="0">
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
<dx:ASPxButton ID="ASPxButton1" runat="server"
OnClick="ASPxButton1_Click"
Text="SaveLayout">
</dx:ASPxButton>
</td>
<td>
</td>
<td>
<dx:ASPxButton ID="ASPxButton2" runat="server"
OnClick="ASPxButton2_Click"
Text="RestoreLayout">
</dx:ASPxButton>
</td>
</tr>
</table>
</div>
</form>
</body>
</html>