Infragistics® WPF 2016.1
Saving and Loading User Customizations (xamPivotGrid)

Topic Overview

Purpose

This topic explains how to save and load the user customizations made to the way the data is presented in the xamPivotGrid™ control.

Required background

The following topics are prerequisites to understanding this topic:

Topic

Purpose

Binding xamPivotGrid to Data

This topic serves as an overview of the data sources supported by the xamPivotGrid control.

xamPivotGrid Interactions

This is a group of topics explaining the main interactions with the xamPivotGrid control that can be performed either through the UI or in code.


In this topic


Saving and Loading Data Source Customizations – Overview

User-customizable aspects of the grid View

In xamPivotGrid, users can customize the View presenting the data slide in the following aspects:

  • Selected database
  • Selected cube
  • Selected measure group
  • Current hierarchies used in rows, columns, filters
  • Current measures
  • Location of the measure list view model (if applicable)
  • Expansion states of filter members
  • Selection states of filter members
  • Expansion states of members (for rows and columns)
  • Currently applied sort orders (for both values and member names within a level)
  • Applied Excel®-style filters (Advanced filters)
  • Deferred layout update state

The information about these customization aspects is stored in the data source controls (FlatDataSource™ and XmlaDataSource™) used by the xamPivotGrid control and and in the OlapXAxis™ component of the xamDataChart™ control and can be saved and consequently loaded.

Saving and Loading Data Source Customizations summary

Saving customizations

In order to save the current view of xamPivotGrid, you need to save the current values of the properties that define that view. All relevant information is available in the data source instance set as the value of the DataSource property of the xamPivotGrid. The DataSourceBase class (from which all other multi-dimensional (OLAP) data sources inherit) exposes extension methods for saving and loading the current state of the data source. The customizations can be written to either a string or in a stream.

The actual saving is done by the SaveCustomizations method. There are two overloads for this method. One returns a string containing the saved customizations, and the other expects a stream into which the customizations are written. You invoke one of them depending on your preferences.

Loading customizations

The LoadCustomizations methods load previously saved customizations. Saved customizations can be loaded from a string or stream. In addition to this, in both cases, an Action can be specified to be executed when the load has completed. Therefore there are four overloads of the LoadCustomizations method, one for each parameter combination.

In practice, the implementation of the loading usually goes together with configuring of some post-load action. For example, because the process of loading the customizations may take some time, you may want to execute some custom code when it is finished, or be notified for its completion. To do this, call one of the LoadCustomizations overloads that accept an action parameter. When the load process finishes, the action is executed. The action accepts a string parameter which will contain descriptions of the errors that occurred during the load process if such errors have occurred.

Requirements

Following are the general requirements for saving and loading customizations:

  • Data requirements

In order for a set of customizations to load, the source and destination data sources must have the same database (metadata) structure. Otherwise the load process will either fail or be incomplete.

  • References
    • Defining the SaveCustomizations and LoadCustomizations extension methods for the DataSourceBase class in the Infragistics.Olap namespace
    • using/Imports directive to the Infragistics.Olap namespace

Properties Saved Upon Customization

The following table maps the configurable aspects that are saved by the SaveCustomizations methods to the values of the respective properties and the data source type to which they apply.

Configurable aspect

Data Source Property

Applicable to:

Selected Database

XmlaDataSource.Database

XmlaDataSource

Selected cube

XmlaDataSource.Cube

XmlaDataSource

Selected Measure group

XmlaDataSource.MeasureGroup

XmlaDataSource

Used hierarchies for rows, columns, filters

DataSourceBase.Rows

DataSourceBase.Columns

DataSourceBase.Filters

All data sources

Used measures

DataSourceBase.Measures

All data sources

Location of the measure list View model (if applicable)

DataSourceBase.MeasureListLocation

All data sources

Expansion states of filter members

IFilterMember.IsExpanded for the filter members in all IFilterViewModels used in the rows, columns, and filters

All data sources

Selection states of filter members

IFilterMember.IsSelected for the filter members in all IFilterViewModels used in the rows, columns, and filters

All data sources

Expansion states of members (for rows and columns)

The result of the call for TupleResolver.IsMemberExpanded, for each member in the row and column tuples.

All data sources

Applied sort orders (for both values and member names within a level)

DataSourceBase.LevelSortDirections

DataSourceBase.SortDescriptors

All data sources

Applied Excel-style filters (advanced filters)

ISupportFilters.FilterExpressions

XmlaDataSource

Deferred layout update state

DataSourceBase.DeferredLayoutUpdate

All data sources



Saving a Data Source Customization – Code Example

Description

The following procedure demonstrates the process of saving the customizations for a data source. To save the user customizations, one of the SaveCustomizations methods is called. The example Code assumes that a variable of type DataSourceBase (or a class inherited from it) named dataSource holds a reference to a data source object.

Code

Saving a customization to a string

In C#:

String customizations = dataSource.SaveCustomizations();

In Visual Basic:

Dim customizations = dataSource.SaveCustomizations()

Saving a customization to a stream

In C#:

using (Stream stream = [initialize the stream here])
{
    dataSource.SaveCustomizations(stream);
}

In Visual Basic:

Using stream As [initialize the stream here]
   dataSource.SaveCustomizations(stream)
End Using

Loading Data Source Customizations – Procedure

Introduction

The following procedure loads a previously saved customization of a multi-dimensional (OLAP) data source.

The procedure contains an optional step of configuring a post-load action which, in this case, is displaying load errors in a message box. To that purpose, a sample method (LoadCompletedAction) is defined.

Prerequisites

To complete the procedure, you need the following:

  • A variable of type DataSourceBase (or a class inherited from it) named dataSource holding a reference to a data source object

Overview

Following is a conceptual overview of the process:

1. (Optional) Defining a post-load action

2. Calling the LoadCustomizations method

Steps

The following demonstrate how to load a customization.

Step

Description

1. (Optional) Define a post-load action.

The following code snippet defines a sample method which displays the load errors in a message box:

In C#:

public void LoadCompletedAction(string loadErrors)
{
   if(!string.IsNullOrWhiteSpace(loadErrors))
   {
     MessageBox.Show(loadErrors);
   }
}

In Visual Basic:

Public Sub LoadCompletedAction(loadErrors As String)
      If Not String.IsNullOrWhiteSpace(loadErrors) Then
            MessageBox.Show(loadErrors)
      End If
End Sub
2. Call the LoadCustomizations method.

To load customizations that have been earlier saved to a string or a stream, call one of the LoadCustomization methods passing the String or Stream argument.

The following code snippet demonstrates how to load a customization from a string when passing an action argument.

In C#:

dataSource.LoadCustomizations(customizations, LoadCompletedAction);
// or
using(Stream customizations = [initialize stream here])
{
   dataSource.LoadCustomizations(customizations, LoadCompletedAction);
}

In Visual Basic:

dataSource.LoadCustomizations(customizations, LoadCompletedAction)
‘ or
Using stream As [initialize the stream here]
   dataSource.LoadCustomizations(customizations, LoadCompletedAction)
End Using

If you prefer not to specify the action parameter (LoadCompletedAction), use the overloads of the LoadCustomizations methods that accept only one argument.



Related Content

Samples

The following samples provide additional information related to this topic.

Sample

Purpose

This sample demonstrates saving and loading the user customizations made to the xamPivotGrid.



 

 


Copyright © 2008-2016 Infragistics, Inc. All rights reserved.

E-mail your feedback on this topic.