Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Collapse]ASP.NET Controls and MVC Extensions
 [Expand]Prerequisites
 [Expand]What's Installed
 [Expand]Common Concepts
 [Collapse]ASP.NET WebForms Controls
  [Expand]Reporting
  [Expand]Chart Control
  [Expand]Grid View
  [Expand]Card View
  [Expand]Vertical Grid
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Image and Data Browsing
  [Expand]Docking and Popups
  [Expand]Site Navigation and Layout
  [Expand]File Management
  [Expand]Multi-Use Site Controls
  [Expand]Scheduler
  [Expand]HTML Editor
  [Collapse]Pivot Grid
   [Expand]Getting Started
   [Expand]Fundamentals
   [Expand]Binding to Data
   [Expand]Data Shaping
   [Expand]Data Analysis
   [Expand]Data Formatting
   [Collapse]Layout
     Hierarchical Value Arrangement
     Compact Layout for Hierarchical Row Values
     Field Location and Order
     Data Cell Layout
     Field Groups
    [Expand]Customization Form
     Save and Restore Layout
    [Expand]Paging and Scrolling
   [Expand]Appearance
   [Expand]Data Export
   [Expand]Design-Time Features
   [Expand]UI Elements
   [Expand]Examples
   [Expand]End-User Capabilities
   [Expand]Member Tables
  [Expand]Tree List
  [Expand]Gauges
  [Expand]Data Editors
  [Expand]Spell Checker
  [Expand]Query Builder
 [Expand]ASP.NET MVC Extensions
 [Expand]Localization
 [Expand]Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Save and Restore Layout

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.

Expanded Basics

ASPxPivotGrid exposes the following methods that allow you to save the pivot grid layout to a stream or string:

ASPxPivotGrid.SaveLayoutToStream Saves the pivot grid layout to the specified stream.
ASPxPivotGrid.SaveLayoutToString Saves the pivot grid layout to the specified string.

To restore the previously saved layout, use the following methods:

ASPxPivotGrid.LoadLayoutFromStream Restores the pivot grid layout from the specified stream.
ASPxPivotGrid.LoadLayoutFromString Restores the pivot grid layout from the specified string.
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.

Expanded 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:

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 sysytem registry).

Options exposed by the OptionsLayoutGrid.Columns property are listed below.

OptionsColumnLayout.AddNewColumns 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.
OptionsColumnLayout.RemoveOldColumns 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.
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.

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 PivotGridWebOptionsLayout.FullLayout static property as the options parameter.

Expanded 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.

Expanded Example: How to Save and Restore Layout

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1879.

The following example shows how to save a pivot grid's layout to a string and then restore it.

How would you rate this topic?​​​​​​​