Save and Restore Layout
- 9 minutes to read
The Pivot Grid allows you to save its layout and restore it. The layout information includes all the settings that specify the visibility and size of visual elements, their appearance settings, filtering, sorting, and so on.
Tip
Demo: Undo/Redo
Basics
Use the following methods to save the pivot grid’s layout to a stream or string:
| API | Description |
|---|---|
| ASPxPivotGrid.SaveLayoutToStream | Saves the pivot grid layout to the specified stream, using the specified settings. |
| ASPxPivotGrid.SaveLayoutToString | Saves the pivot grid layout to the specified string. |
Use the following methods to restore a saved layout:
| API | Description |
|---|---|
| ASPxPivotGrid.LoadLayoutFromStream | Restores the pivot grid layout from the specified stream, using the specified settings. |
| ASPxPivotGrid.LoadLayoutFromString | Restores the pivot grid layout from the specified string, using the specified settings. |
Note
To save and restore the pivot grid’s layout, 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
Use the SaveLayoutTo… and LoadLayoutFrom… methods to save and restore the layout with the following settings:
- visibility state, position, and field sizes;
- sorting and grouping settings;
- applied filters;
- summary information;
- all the settings grouped within the control’s ASPxPivotGrid.OptionsView object.
Use the options parameter of the PivotGridWebOptionsLayout type to specify the appearance, behavior, customization, and other options that are not saved/restored. Create an instance of the PivotGridWebOptionsLayout class, customize it, and pass it as the options parameter. Only options that are enabled in this object are saved/restored. Specific options that are disabled in the options parameter are not affected.
The ASPxPivotGrid.OptionsLayout property provides the following options:
| API | Description |
|---|---|
| OptionsLayoutGrid.StoreAllOptions | 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. |
| OptionsLayoutGrid.StoreAppearance | 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. |
| PivotGridWebOptionsLayout.StoreClientSideEvents | 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. |
| OptionsLayoutGrid.StoreDataSettings | 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. |
| OptionsLayoutGrid.StoreVisualOptions | 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. |
| PivotGridOptionsLayout.AddNewGroups | Gets or sets whether to retain field groups that exist in the current control layout, but do not exist in the layout being restored. |
| OptionsLayoutGrid.Columns | Contains options that specify how the columns’ and bands’ settings are stored to and restored from storage (a stream, xml file or system registry). |
Options the OptionsLayoutGrid.Columns property expose are listed below.
| API | Description |
|---|---|
| OptionsColumnLayout.AddNewColumns | Gets or sets whether columns that exist in the current control but do not exist in a layout when it is restored should be retained. |
| OptionsColumnLayout.RemoveOldColumns | Gets or sets whether the columns that exist in a layout when it is restored but that do not exist in the current control should be discarded or added to the control. |
| OptionsColumnLayout.StoreLayout | 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. |
| OptionsColumnLayout.StoreAppearance | 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. |
| OptionsColumnLayout.StoreAllOptions | 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. |
To manage the layout’s columns use OptionsColumnLayout.AddNewColumns / OptionsColumnLayout.RemoveOldColumns.
New columns are fields in the control, old columns are fields in the saved layout.
If old and new fields have the same ID, the control applies the saved layout changes to the fields in the control.
If old and new fields have the different ID, the behavior is as follows:
If both properties are true, the Pivot Grid removes the fields from the saved layout and keeps the fields in the control.
If both properties are false, the Pivot Grid restores the fields from the layout and removes the fields from the control.
If AddNewColumns is true and RemoveOldColumns is false, the Pivot Grid restores the fields from the layout and keeps the fields in the control.
If AddNewColumns is false and RemoveOldColumns is true, the Pivot Grid removes the fields from the layout and control.
To save all layout options (without appearance, data or 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 manage how a layout is upgraded when it is loaded from a data store (a stream or string).
Handle the ASPxPivotGrid.LayoutUpgrade event to manage how the ASPxPivotGrid layout is upgraded. The event occurs when a layout is restored from a data store (the ASPxPivotGrid.LoadLayoutFromStream or ASPxPivotGrid.LoadLayoutFromString method), and its version differs from the version of the current ASPxPivotGrid layout.
Use the OptionsLayoutBase.LayoutVersion property to specify the layout version. This can be compared to the current layout’s version specified in the OptionsLayoutBase.LayoutVersion property. If the versions do not match, the layout restoration is canceled.
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.
Handle the ASPxPivotGrid.BeforeLoadLayout event to prevent the layout from being restored and applied to the control. Set the event parameter LayoutAllowEventArgs.Allow property to false to stop the layout from being restored.
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.
<%@ 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>
Example: How to manage Pivot Grid Layout
The following example demonstrates how to save the layout from the one Pivot Grid and apply it to another Pivot Grid.
The old Pivot Grid contains the “Year” and “Quarter” fields that do not exist in the new Pivot Grid. The new Pivot Grid contains the “Country” and “Sales Person” fields that do not exist in the old Pivot Grid. When you apply the saved layout to the new Pivot Grid control, the “Year” and “Quarter” fields from the saved layout replace the “Country” and “Sales Person” fields. This behavior is set by the OptionsColumnLayout.RemoveOldColumns and OptionsColumnLayout.AddNewColumns properties. In this example, the RemoveOldColumns and AddNewColumns properties are set to false. As a result, the Pivot Grid restores the fields that exist in the saved layout, and leaves fields that exist in the Pivot Grid and in the saved layout with the same Name values.
The LayoutVersion property is defined for two Pivot Grid controls. When you click the “Restore layout” button (and the saved layout is restored from a data store), the ASPxPivotGrid.LayoutUpgrade event is raised since the layout versions are different. As a result, a new “Quantity” field is added to the new Pivot Grid control.
The Pivot Grid uses a field’s Name property value to determine fields in a stored layout.