Custom Item Export in Web Dashboards

• Nov 03, 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 the item’s caption and select the format:

To display the Export To option for an individual custom dashboard item, override the allowExportSingleItem method in the item’s configuration object:

FunnelChartItem.js

class FunnelChartItemViewer extends Dashboard.CustomItemViewer { 
   //...
    allowExportSingleItem() {
        return true;
    }
)

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 DashboardConfigurator.CustomizeExportDocument event to customize the generated Excel document. Call the e.GetDashboardItem(String) method to get the exported custom dashboard item and the e.GetItemData(String) method to obtain the custom item’s data.

The code snippet below demonstrates how to generate an XLSX document. The code uses the Spreadsheet Document API to modify the generated document’s layout and content. This library is part of the DevExpress Office File API suite.

Startup.cs

using DevExpress.DashboardAspNetCore;
using DevExpress.DashboardCommon;
using DevExpress.DashboardCommon.ViewerData;
using DevExpress.DashboardWeb;
using DevExpress.Spreadsheet;
using System.Collections.Generic; 
using System.Drawing;
// ...
public void ConfigureServices(IServiceCollection services) {
    //...
    services.AddScoped<DashboardConfigurator>((IServiceProvider serviceProvider) => {
        DashboardConfigurator configurator = new DashboardConfigurator();
        // ...
        configurator.CustomizeExportDocument += Configurator_CustomizeExportDocument;

        return configurator;
    });

private void Configurator_CustomizeExportDocument(object sender, CustomizeExportDocumentWebEventArgs e) {
    if (e.ExportAction == DashboardExportAction.ExportToExcel && e.ExcelExportOptions.Format == ExcelFormat.Xlsx) {
        CustomDashboardItem item = e.GetDashboardItem("customItemDashboardItem2") 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);
        }
    }
}

The following image demonstrates the resulting document:

You can find the source code in the following example:

View Example

Export to Image and PDF

To enable export for a custom dashboard item, you should specify the export logic in the item’s configuration object. Otherwise, the export operation produces an empty document.

A custom item does not support the default export mechanism. You cannot use classes such as WebDashboardExporter or ASPxDashboardExporter to export custom items. You need to follow one of the methods below to generate an output image.

• On the client, override the CustomItemViewer.getExportInfo method and pass an object with the image field. Use the Base64 scheme to encode the image in ASCII format to display a custom item in the exported document.

• If you cannot generate an image on the client, implement your own export logic on the server. Handle the DashboardConfigurator.CustomExport or ASPxDashboard.CustomExport event.

The following code snippet allows you to export a custom Funnel Chart item as Image or PDF:

FunnelD3.js

class FunnelD3ItemViewer extends Dashboard.CustomItemViewer {
    constructor(model, container, options) {
         this.exportingImage = new Image();
    }
    _update(data, options) {
            this._ensureFunnelSettings();
            if (!!data) {
                this.funnelSettings.data = data;
            }
            if (!!options) {
                $.extend(true, this.funnelSettings.options, options);
            }
            if (!!this.funnelViewer) {
                this.funnelViewer.draw(this.funnelSettings.data, this.funnelSettings.options);
                this._updateExportingImage();
            }
        }
    _updateExportingImage() {
        const svg = this.funnelContainer.firstElementChild;
        const str = new XMLSerializer().serializeToString(svg),
            encodedData = 'data:image/svg+xml;base64,' + window.btoa(window['unescape'](encodeURIComponent(str)));
        this.exportingImage.src = encodedData;
    }
    _hasArguments() {
        return this.getBindingValue('Arguments').length > 0;
    }
    _getImageBase64() {
        let canvas = document.createElement('canvas');
        canvas.width = this.funnelContainer.clientWidth;
        canvas.height = this.funnelContainer.clientHeight;
        const canvasContext = canvas.getContext('2d');
        canvasContext && canvasContext.drawImage(this.exportingImage, 0, 0);
        return canvas.toDataURL().replace('data:image/png;base64,', '');
    }
}

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.