DashboardExporter.CustomItemExportControlCreating Event

Occurs when the DashboardExporter component exports a custom item.

Namespace: DevExpress.DashboardCommon

Assembly: DevExpress.Dashboard.v24.1.Core.dll

NuGet Package: DevExpress.Dashboard.Core

Declaration

C#

public event CustomItemExportControlCreatingEventHandler CustomItemExportControlCreating

VB.NET

Public Event CustomItemExportControlCreating As CustomItemExportControlCreatingEventHandler

Event Data

The CustomItemExportControlCreating event's data class is CustomItemExportControlCreatingEventArgs. The following properties provide information specific to this event:

Property	Description
CustomItemType	Gets the custom item’s type.
DashboardItem	Gets the exported custom dashboard item.
ExportControlProvider	Gets or sets the object that specifies a printable control for the custom dashboard item before it is exported.

Remarks

Follow the steps below to export a custom dashboard item:

1. Create a class that implements the ICustomExportControlProvider interface to configure a printable control that corresponds to a custom item in the dashboard.

2. In the CustomItemExportControlCreating event handler, assign this class instance to the ExportControlProvider property to use the configured printable control for a custom dashboard item’s export.

The following example shows how use the DashboardExporter component in a console application to export a dashboard with a custom Funnel item:

View Example: BI Dashboard - Non-Visual Custom Export

Implement the ICustomExportControlProvider Interface

Create a class that implements the ICustomExportControlProvider interface (FunnelItemExportControlProvider in this example). FunnelItemExportControlProvider is used to configure the printable XRChart control for the custom Funnel item in the dashboard.

The ICustomExportControlProvider.GetPrintableControl method specifies the printable XRChart control that is used to export the custom Funnel. The method gets CustomItemExportInfo and CustomItemData objects as parameters.

The CustomItemExportInfo object contains the custom Funnel’s export settings: ExportMode and Selection.

The ChartControl.SelectionMode property is updated according to the master filter mode. The SetSelection method updates the custom control based on the current master filter selection.

The ConfigureSeries method is used to data bind and configure the custom Funnel chart’s series. The CustomItemData.GetBindings method gets a CustomItemBindingValue collection. Each object in this collection contains information about data items stored in a custom item. The object’s UniqueId property value can be used as a data member when a custom control is bound to data.

FunnelItemExportControlProvider.cs

using System.Collections.Generic;
using System.Linq;
using DevExpress.DashboardCommon;
using DevExpress.XtraCharts;
using DevExpress.XtraReports.UI;

namespace DashboardExporterApp {
    public class FunnelItemExportControlProvider : ICustomExportControlProvider {
        readonly CustomDashboardItem dashboardItem;
        public FunnelItemExportControlProvider(CustomDashboardItem dashboardItem) {
            this.dashboardItem = dashboardItem;
        }
        XRControl ICustomExportControlProvider.GetPrintableControl(CustomItemData customItemData, 
            CustomItemExportInfo exportInfo) {
            XRChart chart = new XRChart();
            chart.Legend.Visibility = DevExpress.Utils.DefaultBoolean.True;
            chart.CustomDrawSeriesPoint += CustomDrawSeriesPoint;
            DashboardFlatDataSource flatData = customItemData.GetFlatData(new DashboardFlatDataSourceOptions() {
                AddColoringColumns = true });
            ConfigureSeries(chart, customItemData, flatData, exportInfo.DrillDownValues.Count);
            SetSelectionMode(chart);
            SetSelection(chart, exportInfo.Selection, flatData);
            return chart;
        }
        void ConfigureSeries(XRChart chart, CustomItemData customItemData,
            DashboardFlatDataSource flatData, int drillDownLevel) {
            chart.Series.Clear();
            Series series = new Series("A Funnel Series", ViewType.Funnel);
            IList<CustomItemBindingValue> values = customItemData.GetBindings("Value");
            IList<CustomItemBindingValue> arguments = customItemData.GetBindings("Arguments");
            if(values.Count > 0 && arguments.Count > 0) {
                series.DataSource = flatData;
                series.ValueDataMembers.AddRange(values[0].UniqueId);
                if(dashboardItem.InteractivityOptions.IsDrillDownEnabled)
                    series.ArgumentDataMember = arguments[drillDownLevel].UniqueId;
                else
                    series.ArgumentDataMember = arguments.Last().UniqueId;
                series.ColorDataMember = flatData.GetColoringColumn(values[0].UniqueId).Name;
            }
            ((FunnelSeriesLabel)series.Label).Position = FunnelSeriesLabelPosition.Center;
            chart.Series.Add(series);
        }
        void SetSelectionMode(XRChart chart) {
            chart.Chart.SeriesSelectionMode = SeriesSelectionMode.Point;
            switch(dashboardItem.InteractivityOptions.MasterFilterMode) {
                case DashboardItemMasterFilterMode.None:
                    chart.Chart.SelectionMode = ElementSelectionMode.None;
                    break;
                case DashboardItemMasterFilterMode.Single:
                    chart.Chart.SelectionMode = ElementSelectionMode.Single;
                    break;
                case DashboardItemMasterFilterMode.Multiple:
                    chart.Chart.SelectionMode = ElementSelectionMode.Extended;
                    break;
                default:
                    chart.Chart.SelectionMode = ElementSelectionMode.None;
                    break;
            }
        }
        void SetSelection(XRChart chart, CustomItemSelection selection, 
            DashboardFlatDataSource flatData) {
            foreach(DashboardFlatDataSourceRow row in selection.GetDashboardFlatDataSourceRows(flatData))
                chart.Chart.SelectedItems.Add(row);
        }
        void CustomDrawSeriesPoint(object sender, CustomDrawSeriesPointEventArgs e) {
            e.LabelText = e.SeriesPoint.Argument + " - " + e.LabelText;
            e.LegendText = e.SeriesPoint.Argument;
        }
    }
}

FunnelItemExportControlProvider.vb

Imports System.Collections.Generic
Imports System.Linq
Imports DevExpress.DashboardCommon
Imports DevExpress.XtraCharts
Imports DevExpress.XtraReports.UI

Namespace DashboardExporterApp
    Public Class FunnelItemExportControlProvider
        Implements ICustomExportControlProvider

        Private ReadOnly dashboardItem As CustomDashboardItem

        Public Sub New(ByVal dashboardItem As CustomDashboardItem)
            Me.dashboardItem = dashboardItem
        End Sub
        Private Function ICustomExportControlProvider_GetPrintableControl(ByVal customItemData As CustomItemData, ByVal exportInfo As CustomItemExportInfo) As XRControl Implements ICustomExportControlProvider.GetPrintableControl
            Dim chart As New XRChart()
            chart.Legend.Visibility = DevExpress.Utils.DefaultBoolean.True
            AddHandler chart.CustomDrawSeriesPoint, AddressOf CustomDrawSeriesPoint
            Dim flatData As DashboardFlatDataSource = customItemData.GetFlatData(New DashboardFlatDataSourceOptions() With {.AddColoringColumns = True})
            ConfigureSeries(chart, customItemData, flatData, exportInfo.DrillDownValues.Count)
            SetSelectionMode(chart)
            SetSelection(chart, exportInfo.Selection, flatData)
            Return chart
        End Function
        Private Sub ConfigureSeries(ByVal chart As XRChart, ByVal customItemData As CustomItemData, ByVal flatData As DashboardFlatDataSource, ByVal drillDownLevel As Integer)
            chart.Series.Clear()
            Dim series As New Series("A Funnel Series", ViewType.Funnel)
            Dim values As IList(Of CustomItemBindingValue) = customItemData.GetBindings("Value")
            Dim arguments As IList(Of CustomItemBindingValue) = customItemData.GetBindings("Arguments")
            If values.Count > 0 AndAlso arguments.Count > 0 Then
                series.DataSource = flatData
                series.ValueDataMembers.AddRange(values(0).UniqueId)
                If dashboardItem.InteractivityOptions.IsDrillDownEnabled Then
                    series.ArgumentDataMember = arguments(drillDownLevel).UniqueId
                Else
                    series.ArgumentDataMember = arguments.Last().UniqueId
                End If
                series.ColorDataMember = flatData.GetColoringColumn(values(0).UniqueId).Name
            End If
            CType(series.Label, FunnelSeriesLabel).Position = FunnelSeriesLabelPosition.Center
            chart.Series.Add(series)
        End Sub
        Private Sub SetSelectionMode(ByVal chart As XRChart)
            chart.Chart.SeriesSelectionMode = SeriesSelectionMode.Point
            Select Case dashboardItem.InteractivityOptions.MasterFilterMode
                Case DashboardItemMasterFilterMode.None
                    chart.Chart.SelectionMode = ElementSelectionMode.None
                Case DashboardItemMasterFilterMode.Single
                    chart.Chart.SelectionMode = ElementSelectionMode.Single
                Case DashboardItemMasterFilterMode.Multiple
                    chart.Chart.SelectionMode = ElementSelectionMode.Extended
                Case Else
                    chart.Chart.SelectionMode = ElementSelectionMode.None
            End Select
        End Sub
        Private Sub SetSelection(ByVal chart As XRChart, ByVal selection As CustomItemSelection, ByVal flatData As DashboardFlatDataSource)
            For Each row As DashboardFlatDataSourceRow In selection.GetDashboardFlatDataSourceRows(flatData)
                chart.Chart.SelectedItems.Add(row)
            Next row
        End Sub
        Private Sub CustomDrawSeriesPoint(ByVal sender As Object, ByVal e As CustomDrawSeriesPointEventArgs)
            e.LabelText = e.SeriesPoint.Argument & " - " & e.LabelText
            e.LegendText = e.SeriesPoint.Argument
        End Sub
    End Class
End Namespace

Handle the CustomItemExportControlCreating Event

Handle the CustomItemExportControlCreating event and assign the FunnelItemExportControlProvider object to the ExportControlProvider property. The property is used to specify the printable control that corresponds to the exported custom Funnel item.

Program.cs

using DevExpress.DashboardCommon;
//...
DashboardExporter exporter = new DashboardExporter();
exporter.CustomItemExportControlCreating += Exporter_CustomItemExportControlCreating;

static void Exporter_CustomItemExportControlCreating(object sender, 
    CustomItemExportControlCreatingEventArgs e) {
    if(e.CustomItemType == "FunnelItem")
        e.ExportControlProvider = new FunnelItemExportControlProvider(e.DashboardItem);
}

Program.vb

Imports DevExpress.DashboardCommon
'...
DashboardExporter exporter = new DashboardExporter();
exporter.CustomItemExportControlCreating += Exporter_CustomItemExportControlCreating;

Private Shared Sub Exporter_CustomItemExportControlCreating(ByVal sender As Object, ByVal e As CustomItemExportControlCreatingEventArgs)
            If e.CustomItemType = "FunnelItem" Then
                e.ExportControlProvider = New FunnelItemExportControlProvider(e.DashboardItem)
            End If
End Sub