Custom Item Export in WinForms Dashboards

• Nov 01, 2023
• 4 minutes to read

You can export custom dashboard items to the following formats:

• Excel (XLS, XLSX)
• PDF
• Image

To export a custom dashboard item, click the Export To button in its caption and select a format:

The following sections explain how to configure the export of custom dashboard items to different formats.

Export to Excel

The Dashboard control exports custom item data in tabular format. Each column corresponds to a data item.

Handle the CustomizeExportDocument event to customize the generated Excel document. Call the e.GetItemData(String) method to obtain the custom item’s data.

The code snippet below demonstrates how to generate a custom XLSX document. The code uses the Spreadsheet Document API for document layout and content customization. This library is part of the DevExpress Office File API suite).

Form1.cs

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Drawing;
using System.Linq;
using System.Windows.Forms;
using DevExpress.DashboardCommon;
using DevExpress.DashboardCommon.ViewerData;
using DevExpress.Spreadsheet;
// ...
dashboardDesigner1.CustomizeExportDocument += DashboardDesigner1_CustomizeExportDocument;
// ...
 private void DashboardDesigner1_CustomizeExportDocument(object sender, CustomizeExportDocumentEventArgs e){
    if (e.ExportAction == DashboardExportAction.ExportToExcel && e.ExcelExportOptions.Format == ExcelFormat.Xlsx) {
        CustomDashboardItem item = dashboardDesigner1.Dashboard.Items.FirstOrDefault(i => i.ComponentName == e.ItemComponentName) as CustomDashboardItem;

        if (item != null) {
            DevExpress.Spreadsheet.Workbook workbook = new DevExpress.Spreadsheet.Workbook();
            Worksheet worksheet = workbook.Worksheets[0];

            MultiDimensionalData itemData = e.GetItemData(e.ItemComponentName);
            CustomItemData customItemData = new CustomItemData(item, itemData);

            DashboardFlatDataSource flatData = customItemData.GetFlatData();
            IList<DashboardFlatDataColumn> columns = flatData.GetColumns();
            for (int colIndex = 0; colIndex < columns.Count; colIndex++){
                worksheet.Cells[0, colIndex].Value = columns[colIndex].DisplayName;
                worksheet.Cells[0, colIndex].FillColor = Color.LightGreen;
                worksheet.Cells[0, colIndex].Font.FontStyle = SpreadsheetFontStyle.Bold;
                int headerOffset = 1;
                for (int rowIndex = 0; rowIndex < flatData.Count; rowIndex++)
                    worksheet.Cells[rowIndex + headerOffset, colIndex].Value = flatData.GetDisplayText(columns[colIndex].Name, rowIndex);
            }
            e.Stream.SetLength(0);
            workbook.SaveDocument(e.Stream, DocumentFormat.Xlsx);
        }
    }
}

Form1.vb

Imports System
Imports System.Collections.Generic
Imports System.Collections.ObjectModel
Imports System.Drawing
Imports System.Linq
Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardCommon.ViewerData
Imports DevExpress.Spreadsheet
' ...
Private dashboardDesigner1.CustomizeExportDocument += AddressOf DashboardDesigner1_CustomizeExportDocument
' ...
Private Sub DashboardDesigner1_CustomizeExportDocument(ByVal sender As Object, ByVal e As CustomizeExportDocumentEventArgs)
  If e.ExportAction = DashboardExportAction.ExportToExcel AndAlso e.ExcelExportOptions.Format = ExcelFormat.Xlsx Then

    Dim item As CustomDashboardItem = TryCast(dashboardDesigner1.Dashboard.Items.FirstOrDefault(Function(i) i.ComponentName = e.ItemComponentName), CustomDashboardItem)

    If item IsNot Nothing Then
      Dim workbook As New DevExpress.Spreadsheet.Workbook()
      Dim worksheet As Worksheet = workbook.Worksheets(0)

      Dim itemData As MultiDimensionalData = e.GetItemData(e.ItemComponentName)
      Dim customItemData As New CustomItemData(item, itemData)

      Dim flatData As DashboardFlatDataSource = customItemData.GetFlatData()
      Dim columns As IList(Of DashboardFlatDataColumn) = flatData.GetColumns()
      For colIndex As Integer = 0 To columns.Count - 1
        worksheet.Cells(0, colIndex).Value = columns(colIndex).DisplayName
        worksheet.Cells(0, colIndex).FillColor = Color.LightGreen
        worksheet.Cells(0, colIndex).Font.FontStyle = SpreadsheetFontStyle.Bold
        Dim headerOffset As Integer = 1
        For rowIndex As Integer = 0 To flatData.Count - 1
          worksheet.Cells(rowIndex + headerOffset, colIndex).Value = flatData.GetDisplayText(columns(colIndex).Name, rowIndex)
        Next rowIndex
      Next colIndex
      workbook.SaveDocument(e.Stream, DocumentFormat.Xlsx)
    End If
  End If
End Sub

The following image demonstrates the resulting document:

You can find the source code in the following example:

View Example

Export to PDF and Image

Export to PDF and Image is available for custom items whose underlying controls support the IPrintableComponentBase interface.

To enable export for a custom dashboard item, specify the export logic in the item’s configuration object (a CustomControlProviderBase descendant). Otherwise, the export operation produces an empty document:

Override the CustomControlProviderBase.GetPrintableControl method to obtain a printable control. This method must return an XRControl. This is the common ancestor for all controls that you can use in DevExpress Reports. The example below uses a PrintableComponentContainer report control.

FunnelItemControlProvider.cs

using DevExpress.XtraReports.UI;
using DevExpress.DashboardCommon;

namespace TutorialsCustomItems {
    public class FunnelItemControlProvider : CustomControlProviderBase {
        protected override XRControl GetPrintableControl(CustomItemData customItemData, CustomItemExportInfo info) {
            PrintableComponentContainer container = new PrintableComponentContainer();
            container.PrintableComponent = chart;
            return container;
        }
    }
}

FunnelItemControlProvider.vb

Imports DevExpress.XtraReports.UI
Imports DevExpress.DashboardCommon

Namespace TutorialsCustomItems
    Public Class FunnelItemControlProvider
        Inherits CustomControlProviderBase
        Protected Overrides Function GetPrintableControl(ByVal customItemData As CustomItemData, ByVal info As CustomItemExportInfo) As XRControl
            Dim container As New PrintableComponentContainer()
            container.PrintableComponent = chart
            Return container
        End Function
    End Class
End Namespace

As a result, custom item data appears in the exported document:

You can find the source code in the following example:

View Example

Post-Process Excel and PDF Files

You can post-process resulting Excel and PDF files with the help of dedicated DevExpress libraries (collectively known as DevExpress Office File API):

• PDF Document API helps you edit, merge, split, password-protect, and digitally sign PDF files.
• Spreadsheet Document API helps you manage worksheets, cells, values and formulas, graphics, charts, pivot tables, and other objects.

PDF Document API and Spreadsheet Document API work in applications that target a variety of platforms (Windows Forms, WPF, ASP.NET Web Forms, ASP.NET MVC, ASP.NET Core, Blazor, MAUI) and operating systems (Windows, Linux, macOS).

Office File API is included into the DevExpress Universal Subscription - the same subscription that includes DevExpress Dashboard.