Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Expand]Application Model
  [Expand]UI Construction
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Collapse]Extra Modules
   [Expand]Audit Trail Module Overview
    Business Class Library Customization Module
    Chart Module
    Clone Object Module
   [Expand]Conditional Appearance Module Overview
   [Expand]Dashboards Module
    File Attachments Module Overview
    HTML Property Editor Module
   [Expand]Notifications Module
    KPI Module
   [Expand]Maps Module
   [Collapse]Pivot Chart Module
     Pivot Chart Module Overview
     Data Bind Aspects
     Distribute an Analysis with the Application
    Pivot Grid Module
   [Expand]Reports V2 Module
   [Expand]Reports Module (Obsolete)
   [Expand]Scheduler Module
    Script Recorder Module
   [Expand]State Machine Module
   [Expand]TreeList Editors Module
   [Expand]Validation Module
    View Variants Module
   [Expand]Workflow Module
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Pivot Chart Module Overview

The PivotChart module provides the capability to analyze data using the XtraPivotGrid, ASPxPivotGrid and XtraCharts controls developed by DevExpress. The XtraPivotGrid and ASPxPivotGrid controls (for Windows Forms and ASP.NET platforms respectively) provide end-users with an extremely intuitive experience in slicing and presenting data, and deliver numerous layout customization options with total end-user control over each individual on-screen report. Regardless of the perspective, data can be rendered to answer business questions. The XtraCharts library is designed for both Windows Forms and ASP.NET to offer you a comprehensive set of 2D and 3D charts to address a broad range of business needs with ease. The PivotChart module adopts these controls for XAF applications, so you can add the data analysis functionality with ease. This topic details all the basics for using the PivotChart module.

The PivotChart module is presented in two module projects.

  • PivotChartWindowsFormsModule
    Adds references to the DevExpress.ExpressApp.PivotChart.v17.1 and DevExpress.ExpressApp.PivotChart.Win.v17.1 assemblies.
    You can add this module to your Windows Forms module. To do this, invoke the Module Designer and drag PivotChartWindowsFormsModule from the Toolbox to the RequiredModules panel. Alternatively, you can add this module to the Windows Forms application project. To do this, invoke the Application Designer and drag the PivotChartWindowsFormsModule from the Toolbox to the Modules panel. Do not forget to rebuild your solution after making changes in a Designer.
  • PivotChartAspNetModule
    Adds references to the DevExpress.ExpressApp.PivotChart.v17.1 and DevExpress.ExpressApp.PivotChart.Web.v17.1 assemblies.
    You can add this module to the ASP.NET application project. To do this, invoke the Application Designer and drag the PivotChartASPNETModule from the Toolbox to the Modules panel. Alternatively, you can add this module to your ASP.NET module. To do this, invoke the Module Designer and drag the PivotChartASPNETModule from the Toolbox to the RequiredModules panel. Note that in this instance, you will need to manually add pivot templates to the application project. The easiest way to do this is to add the PivotChartASPNETModule module to the application project via the Application Designer and then remove it. This will automatically add all the required templates.
    Do not forget to rebuild your solution after making changes in a Designer.
Note

To see the list of the Pivot Chart module's Controllers and Actions refer to the Built-in Controllers and Actions in Extra Modules topic.

Expanded PivotChart Module Basics

To display data analysis, the PivotChart module contains the AnalysisEditorWin and AnalysisEditorWeb Property Editors for Windows Forms and ASP.NET applications respectively. These Property Editors work with properties that reference objects implementing the IAnalysisInfo interface. This interface has the following members.

  • DataType
    Specifies the type of the objects to be analyzed.
  • Criteria
    Specifies the criteria according to which objects will be retrieved from a database to the collection to be analyzed. Function Criteria Operators are supported.
  • DimensionProperties
    A list of the analyzed object type's properties that will be available for analysis in the pivot grid.
  • ChartSettingsContent
    A byte array representing chart settings.
  • PivotGridSettingsContent
    A byte array representing the configuration of a pivot grid.
  • InfoChanged
    An event raised when some of the IAnalysisInfo object's properties are changed.
  • Self
    Provides access to the current instance of the class that implements the IAnalysisInfo interface. This property's value is displayed by the AnalysisEditorWin and AnalysisEditorWeb Property Editors.

XAF supplies the Analysis class that implements the IAnalysisInfo interface. So, you can simply add the Analysis class to your application's business model to activate the Analysis functionality supplied with the added PivotChart module. However, if you require, you can implement the IAnalysisInfo interface in a custom class or inherit from the Analysis class. The AnalysisEditorWin and AnalysisEditorWeb Property Editors will be used in any case. When implementing a custom class, have a look at the Analysis class located in the %PROGRAMFILES(x86)%\DevExpress 17.1\Components\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl folder.

The Analysis class populates the DimensionProperties list when its DataType property is changed. For this purpose, it calls the GetDimensionProperties method of the ModelDimensionPropertyExtractor object. This object gets information from the Application Model's BOModel | <Class> nodes that define the class that is assigned to the DataType property and its ancestors. Properties whose BOModel | <Class> | OwnMembers | <Member> node has the IModelMemberPivotChartVisibility.IsVisibleInAnalysis property set to true (a default value) are added to the DimensionProperties list. You can change this behavior by inheriting from the static DimensionPropertyExtractor class. The custom Dimension Property Extractor's instance must be set to the DimensionPropertyExtractor's Instance property. To do this, subscribe to the XafApplication.SetupComplete event in your module's Setup method. If the custom Dimension Property Extractor has an overridden IDimensionPropertyExtractor.GetDimensionProperties method, you should implement a custom Analysis class, and call this method, for example, in the ObjectTypeName property setter.

When the PivotChart module is set up in an application, it adds items to the navigation control for the classes that implement the IAnalysisInfo interface. Be careful not to have more than one class that implements the IAnalysisInfo interface in your business model. Otherwise, you will have several Analysis items in the navigation control. In addition to this Application Model customization, the PivotChart module sets the appropriate Property Editors for the IAnalysisInfo.Self and IAnalysis.DataType properties. Other customizations with the List and Detail Views that represent IAnalysisInfo objects are performed by the Business Class Library Customization module, you can add it if required.

The following image demonstrates the Analysis Detail View.

Objects of the specified type are not retrieved from the database to the pivot grid until the BindAnalysisData Action () is pressed. This Action loads only objects that satisfy the criteria specified by the Criteria property and the filter that was previously set in the pivot grid's Prefilter for the current Analysis object.

Note

Field captions are set to the IModelCommonMemberViewItem.Caption property values of the BOModel | <Class> | OwnMembers | <Member> nodes that correspond to analyzed type properties.

After you have changed something in the current Analysis object, use the UnbindAnalysisData Action () to clear the pivot grid's data source. Then, use BindAnalysisData Action () again to load objects using the newly set property values of the Analysis object.

The following image demonstrates an Analysis Detail View with loaded objects. The pivot grid is configured so that you can see how many tasks are assigned to a contact.

In a Windows Forms application:

In an ASP.NET application:

If you switch to the Chart tab, you will see data that is configured in a pivot grid represented by a Chart.

In a Windows Forms application:

In an ASP.NET application:

The AnalysisEditorWin Property Editor uses the AnalysisControlWin control to display data. This control contains a tab control with two pages. One page contains a PivotGrid. The second page contains the ChartControl and two check edits: ShowRowGrandTotalCheckEdit and ShowColumnGrandTotalCheckEdit.

The AnalysisEditorWeb Property Editor uses the AnalysisControlWeb control to display data. This control contains a tab control with two pages. One page contains a PivotGrid. The second page contains the ChartControl, ShowRowGrandTotalCheckEdit and ShowColumnGrandTotalCheckEdit check edits, ChartType combo box and PrintChart button.

The pivot grid's settings are saved to the PivotGridSettingsContent property of the current Analysis object. The settings of the Chart control are saved to the ChartSettingsContent property. So, the next time you invoke a detail View for this Analysis object, the pivot grid and chart are configured in the same way as they were the previous time. Saving and loading settings is performed by the AnalysisEditorWin (AnalysisEditorWeb) editor.

To learn about the capabilities provided by PivotGrid controls in Windows Forms and ASP.NET applications, refer to the Visual Elements (XtraPivotGrid) and Visual Elements (XtraPivotGrid) topics. To learn about the capabilities provided by the ChartControl, refer to Visual Elements (XtraPivotGrid) topic.

Expanded Set Properties To Be Used as a Pivot Grid Data Source

By default, the properties of the class that is assigned to the current Analysis' DataType property are considered as a pivot grid data source (including the inherited properties). However, only those properties whose BOModel | <Class> | OwnMembers | <Member> application model node has the IsVisibleInAnalysis property set to true (a default value) are added to the pivot grid. You may need to add complex path properties to a pivot grid. For instance, if the Task class has a Payment reference property, you may be required to use the Payment.Amount property when configuring data in the pivot grid for Task type objects. To add complex properties at design-time, use the Application Model. In the Model Editor, navigate to the required BOModel | <Class> node (in our example, Task node), and add a new Member node to it. For the newly added node, set the Name property to the required complex path property (in our example, Payment.Amount). This property specifies the property to be added to the pivot grid. Check that the IsVisibleInAnalysis property it set to true for the new member.

At runtime, use the Field List to hide properties that are temporarily unnecessary.

In Windows Forms applications, the Field List has the following buttons.

  • Add
    Use this button to add a property that is not currently available in the pivot grid. In the invoked window, the properties that are displayed in gray are already added to the pivot grid.

    As you can see, you can add complex path properties using this technique.
  • Remove
    Use this button to remove a property that is currently selected in the Field List.
  • Add To
    Use this button to add the property that is currently selected in the Field List to the required area: Row Area, Column Area, Filter Area or Data Area.

When creating an Analysis object in code, you can change the list of properties displayed in the pivot grid using the IAnalysisInfo.DimensionProperties collection. By default, this collection is populated by properties that have the VisibleInAnalysis property set to true in the Application Model. Note that in the built-in Analysis class, this collection is repopulated after the Analysis.ObjectTypeName property has been changed. So, the DimensionProperties collection must be changed after the ObjectTypeName property is set. The following code demonstrates how an object of the Analysis type can be created in the Updater's ModuleUpdater.UpdateDatabaseAfterUpdateSchema method.

For details on how to create Analysis objects in code, refer to the Distribute an Analysis with the Application topic.

Expanded Set Business Object Types to be Available in Analysis

When creating an Analysis object, you should specify the type of the business objects to be analyzed. For this purpose, the DataType property is used. In a UI, this property is displayed by a combo box with an available type list. This list contains only the classes that have the VisibleInReports property set to true in the corresponding BOModel | <Class> node. This property is added to this node by the PivotChart and Reports modules. So, to set this property via the Model Editor, use the project where one of these modules is referenced. Alternatively, you can apply the VisibleInReportsAttribute to a business class in code.

Expanded Access the Pivot Grid and Chart Control in Code

You can take advantage of the PivotGrid and ChartControl used by the AnalysisEditorWin or AnalysisEditorWeb Property Editor. To access the required control in code, create a View Controller and handle the Execute event of the AnalysisDataBindController's BindData Action. Your Controller should be activated for Detail Views only. So, set the Controller's ViewController.TargetViewType property to the DetailView value.

In a Windows Forms module:
Important

The following references are required to compile the code above: DevExpress.Charts.v17.1.Core, DevExpress.ExpressApp.PivotChart.v17.1, DevExpress.ExpressApp.PivotChart.Win.v17.1, DevExpress.XtraCharts.v17.1, DevExpress.XtraCharts.v17.1.UI and DevExpress.XtraPivotGrid.v17.1.

In an ASP.NET module:
Important

The following references are required to compile the code above: DevExpress.ExpressApp.PivotChart.v17.1, DevExpress.ExpressApp.PivotChart.Web.v17.1, DevExpress.XtraCharts.v17.1, DevExpress.XtraCharts.v17.1.Web, DevExpress.Charts.v17.1.Core, DevExpress.PivotGrid.v17.1.Core, DevExpress.Web.ASPxPivotGrid.v17.1 and System.Web.

Expanded See Also

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