ASPxPivotGrid.LayoutUpgrade Event
Occurs when a layout is restored from a data store, and its version is different than that of the control’s current layout version.
Namespace: DevExpress.Web.ASPxPivotGrid
Assembly: DevExpress.Web.ASPxPivotGrid.v19.2.dll
Declaration
Event Data
The LayoutUpgrade event's data class is LayoutUpgradeEventArgs. The following properties provide information specific to this event:
| Property | Description |
|---|---|
| NewHiddenItems | Returns an array of items that exist in the current control but do not exist in the layout being loaded. These items are hidden. This property is in effect for the LayoutControl. |
| PreviousVersion | Returns the textual representation of the previous layout version. |
Remarks
This event allows you to customize the control’s layout after an earlier version of the layout has been loaded from a data store (a stream or a string). For instance, the layout being loaded has overridden specific filtering or sorting settings of the new layout. So, the LayoutUpgrade event can be handled to restore layout settings specific to the new layout.
To enable the LayoutUpgrade event to be called, you need to assign different versions to different layouts via the OptionsLayoutBase.LayoutVersion property of the ASPxPivotGrid.OptionsLayout object.
Consider an example. When the first version of an application was released, the version of the control’s layout was not specified (it was set to an empty string, by default). While running this application, an end-user hid specific fields and saved the layout to a file. Then, a new version of the application was designed (for instance, it added new fields and data could be filtered against any of these fields). At design time, the new layout in the new application should be assigned a specific version (say, “1.1”). In this case, when an end-user runs the new application and loads the previously saved layout from the file, the LayoutUpgrade event will be fired since the versions of the current layout (“1.1”) and the layout being loaded (“”) will not match. In the LayoutUpgrade event handler, you can specify the positions of the newly added fields and restore the filter settings of these fields, if required.
If versions of the current layout and the layout being loaded match, the LayoutUpgrade event will not fire.
The ASPxPivotGrid.OptionsLayout property provides multiple settings that control how the layout is restored from the data store. It also specifies which settings should be stored when the layout is saved to the data store.
The ASPxPivotGrid.BeforeLoadLayout event can be handled, to prevent a layout from being loaded from a data store.