Save and Restore Layout

Jun 16, 2022
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:

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.

Default.aspx (C#)
Default.aspx.cs
Default.aspx.vb
Default.aspx (VB.NET)

aspx

<%@ 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>

csharp

using System;

namespace SaveAndRestoreLayout {
    public partial class _Default : System.Web.UI.Page {
        protected void ASPxButton1_Click(object sender, EventArgs e) {
            Session["Layout"] = ASPxPivotGrid1.SaveLayoutToString();
        }
        protected void ASPxButton2_Click(object sender, EventArgs e) {
            string layout = (string)Session["Layout"];
            if (layout == null) {
                return;
            }
            ASPxPivotGrid1.LoadLayoutFromString(layout);
        }
    }
}

Imports Microsoft.VisualBasic
Imports System

Namespace SaveAndRestoreLayout
    Partial Public Class _Default
        Inherits System.Web.UI.Page
        Protected Sub ASPxButton1_Click(ByVal sender As Object, ByVal e As EventArgs)
            Session("Layout") = ASPxPivotGrid1.SaveLayoutToString()
        End Sub
        Protected Sub ASPxButton2_Click(ByVal sender As Object, ByVal e As EventArgs)
            Dim layout As String = CStr(Session("Layout"))
            If layout Is Nothing Then
                Return
            End If
            ASPxPivotGrid1.LoadLayoutFromString(layout)
        End Sub
    End Class
End Namespace

aspx

<%@ Page Language="vb" AutoEventWireup="true" CodeBehind="Default.aspx.vb"
           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.

View Example: ASPxPivotGrid - How to manage Pivot Grid Layout