Drill Down

  • 10 minutes to read

The Drill Down functionality allows you to reveal additional details when the Chart Control summarizes its data source. For example, a series point of a chart that displays annual sales grouped by category can be expanded to a chart that displays sale dynamics by product.

chart-drill-down-title-image

Note that the Chart Control uses the Breadcrumbs element to display detail levels through which end-users can navigate. Refer to the Breadcrumbs topic for more information about this element.

Demo: Drill Down

How to: Configure the Drill Down

The Chart Control utilizes the Nested Series Templates to display detail data. Each series template can store up to three direct child templates that specify detail data representation. All series templates use ChartControl.DataSource, but detailed templates obtain filtered data. The following list enumerates all child template types and explains data received by a detailed template.

IMPORTANT

The Drill Down only supports series generated by series templates.

NOTE

Drill Down to Argument

The Chart uses the SeriesTemplate.ArgumentDrillTemplate template to reveal detail data when an end-user clicks an argument axis label. Detail data contains all data items that include an argument field value equaling the clicked argument value.

chart-control__drill-down-to-argument

The following code demonstrates how to configure this template.

// In the Form's Load event handler.
SeriesTemplate argumentDrillTemplate = new SeriesTemplate();

List<SaleItem> data = SaleItem.GetTotalIncome();
chartControl.DataSource = data;
chartControl.SeriesTemplate.SeriesDataMember = "Category";
chartControl.SeriesTemplate.ArgumentDataMember = "Company";
chartControl.SeriesTemplate.QualitativeSummaryOptions.SummaryFunction = "SUM([Income])";
chartControl.SeriesTemplate.View = new StackedBarSeriesView();
chartControl.SeriesTemplate.ArgumentDrillTemplate = argumentDrillTemplate;

argumentDrillTemplate.SeriesDataMember = "Category";
argumentDrillTemplate.ArgumentDataMember = "OrderDate";
argumentDrillTemplate.View = new StackedAreaSeriesView();
argumentDrillTemplate.DateTimeSummaryOptions.MeasureUnit = DateTimeMeasureUnit.Month;
argumentDrillTemplate.DateTimeSummaryOptions.UseAxisMeasureUnit = false;
argumentDrillTemplate.DateTimeSummaryOptions.SummaryFunction = "SUM([Income])";
NOTE

A complete sample project is available on GitHub at How to: Create a Drill-Down Chart.

The code snippet above uses the following properties.

Symbol Description
ChartControl.SeriesTemplate Returns the series template the chart uses to generate its series.
SeriesTemplate.ArgumentDrillTemplate Gets or sets the series template that the Chart Control uses to generate detailed series when the Control should display a data slice filtered by an argument.

Drill Down to Series

The SeriesTemplate.SeriesDrillTemplate template specifies how the Chart Control displays detail data when end-users click a series generated by the master template. Detail data contains all data items that include a series field value equaling the selected series identifier.

chart-control__drill-down-to-series

The following code demonstrates how to configure this template.

// In the Form's Load event handler.
SeriesTemplate seriesDrillTemplate = new SeriesTemplate();

List<SaleItem> data = SaleItem.GetTotalIncome();
chartControl.DataSource = data;
chartControl.SeriesTemplate.SeriesDataMember = "Category";
chartControl.SeriesTemplate.ArgumentDataMember = "Company";
chartControl.SeriesTemplate.QualitativeSummaryOptions.SummaryFunction = "SUM([Income])";
chartControl.SeriesTemplate.View = new StackedBarSeriesView();
chartControl.SeriesTemplate.SeriesDrillTemplate = seriesDrillTemplate;

seriesDrillTemplate.SeriesDataMember = "Product";
seriesDrillTemplate.ArgumentDataMember = "Company";
seriesDrillTemplate.QualitativeSummaryOptions.SummaryFunction = "SUM([Income])";
seriesDrillTemplate.View = new StackedBarSeriesView();
NOTE

A complete sample project is available on GitHub at How to: Create a Drill-Down Chart.

The example uses the properties outlined below.

Symbol Description
ChartControl.SeriesTemplate Returns the series template the chart uses to generate its series.
SeriesTemplate.SeriesDrillTemplate Gets or sets the series template that the Chart Control uses to generate detailed series when the Control should display a data slice filtered by a series identifier.

Drill Down to Series Point

The SeriesTemplate.SeriesPointDrillTemplate template specifies how series that display detail data when an end-user selects a series point to expand look. Detail data contains data items that the Chart Control summarizes or aggregates into the selected series point.

chart-control__drill-down-to-series-point

The following code demonstrates how to configure this template.

// In the Form's Load event handler.
SeriesTemplate seriesPointDrillTemplate = new SeriesTemplate();

List<SaleItem> data = SaleItem.GetTotalIncome();
chartControl.DataSource = data;
chartControl.SeriesTemplate.SeriesDataMember = "Category";
chartControl.SeriesTemplate.ArgumentDataMember = "Company";
chartControl.SeriesTemplate.QualitativeSummaryOptions.SummaryFunction = "SUM([Income])";
chartControl.SeriesTemplate.View = new StackedBarSeriesView();
chartControl.SeriesTemplate.SeriesPointDrillTemplate = seriesPointDrillTemplate;

seriesPointDrillTemplate.SeriesDataMember = "Product";
seriesPointDrillTemplate.ArgumentDataMember = "OrderDate";
seriesPointDrillTemplate.DateTimeSummaryOptions.MeasureUnit = DateTimeMeasureUnit.Month;
seriesPointDrillTemplate.DateTimeSummaryOptions.UseAxisMeasureUnit = false;
seriesPointDrillTemplate.DateTimeSummaryOptions.SummaryFunction = "SUM([Income])";
seriesPointDrillTemplate.View = new StackedAreaSeriesView();
NOTE

A complete sample project is available on GitHub at How to: Create a Drill-Down Chart.

The code snippet above uses the following properties.

Symbol Description
ChartControl.SeriesTemplate Returns the series template the chart uses to generate its series.
SeriesTemplate.SeriesPointDrillTemplate Gets or sets the series template that the Chart Control uses to generate detailed series when the Control should display a data slice filtered by a series point.

Note that any Drill Template can contain other nested templates.

chart-control__drill-down-two-level

The following code demonstrates how to configure the chart control to display the second nested data level.

SeriesTemplate argumentDrillTemplate = new SeriesTemplate();
SeriesTemplate secondDetailLevelTemplate = new SeriesTemplate();

// Other SeriesTemplate settings are here.
chartControl.SeriesTemplate.ArgumentDrillTemplate = argumentDrillTemplate;

// Other ArgumentDrillTemplate settings are here.
argumentDrillTemplate.SeriesDrillTemplate = secondDetailLevelTemplate;

secondDetailLevelTemplate.SeriesDataMember = "Product";
secondDetailLevelTemplate.ArgumentDataMember = "OrderDate";
secondDetailLevelTemplate.DateTimeSummaryOptions.MeasureUnit = DateTimeMeasureUnit.Month;
secondDetailLevelTemplate.DateTimeSummaryOptions.SummaryFunction = "SUM([Income])";
secondDetailLevelTemplate.View = new StackedAreaSeriesView();

How to: Manage Drill Down State at Runtime

The chart control provides methods that allow you to drill down/drill up to a specific detail level. Also, the chart diagram stores Drill Down Options that manage how charts behave on a click of its elements.

// In the Form's Load event handler.
chartControl.SelectionMode = ElementSelectionMode.Single;
chartControl.SeriesSelectionMode = SeriesSelectionMode.Point;

if (chartControl.Diagram is XYDiagram diagram) {
    // The following code disables the detail data reveal on click on a chart element.
    diagram.DrillDownOptions.UseMouse = false;
}

bbiDrillDownToSelectedArgument.ItemClick += this.OnDrillDownToSelectedArgumentBarItemClick;
bbiDrillDownToSelectedSeries.ItemClick += this.OnDrillDownToSelectedSeriesBarItemClick;
bbiDrillDownToSelectedSeriesPoint.ItemClick += this.OnDrillDownToSelectedSeriesPointBarItemClick;
bbiDrillUp.ItemClick += this.OnDrillUpBarItemClick;
// ...

// Ribbon Items' Click handlers.
private void OnDrillDownToSelectedArgumentBarItemClick(object sender, ItemClickEventArgs e) {
    if (chartControl.SelectedItems.Count == 0) return;
    SaleItem item = (SaleItem)chartControl.SelectedItems[0];
    chartControl.DrillDownToArgument(item.Company);
}
private void OnDrillDownToSelectedSeriesBarItemClick(object sender, ItemClickEventArgs e) {
    if (chartControl.SelectedItems.Count == 0) return;
    SaleItem item = (SaleItem)chartControl.SelectedItems[0];
    chartControl.DrillDownToSeries(item.Category);
}
private void OnDrillDownToSelectedSeriesPointBarItemClick(object sender, ItemClickEventArgs e) {
    if (chartControl.SelectedItems.Count == 0) return;
    SaleItem item = (SaleItem)chartControl.SelectedItems[0];
    chartControl.DrillDownToSeriesPoint(item);
}
private void OnDrillUpBarItemClick(object sender, ItemClickEventArgs e) {
    chartControl.DrillUp();
}

The following table contains the chart control's methods that manage the Drill Down State.

Method Description
XYDiagram.DrillDownOptions Returns mouse actions and hotkey settings for the Drill Down feature.
DrillDownOptions.UseMouse Gets or sets the value that specifies whether an end user can use the mouse to select the point or series to show detail information.
DrillDownOptions.UseKeyboard Gets or sets the value that specifies whether an end user can use the keyboard to drill down in the chart.
ChartControl.DrillDownToArgument Drills down to the passed argument if the actual series template has the SeriesTemplate.ArgumentDrillTemplate specified.
ChartControl.DrillDownToSeries Drills down to a series with the passed series ID if the actual series template has the SeriesTemplate.SeriesDrillTemplate specified.
ChartControl.DrillDownToSeriesPoint Drills down to the passed series point if the actual series template has the SeriesTemplate.SeriesPointDrillTemplate specified.
ChartControl.DrillUp Drills up if the actual series template is not root (ChartControl.SeriesTemplate) template.
BarButtonItem.ItemClick Occurs when the current item is clicked.
IMPORTANT

The DrillDownTo... methods do not change the drill down state if:

  • the actual series template does not have the corresponding nested template specified;
  • the data source does not contain a value passed as a method's parameter as an argument field value/series field value/data object.

How to: Handle And Prevent Drill Down State Change

The Chart Control provides the ChartControl.DrillDownStateChanging event that allows you to check the data level and prevent revealing or concealing the detail level, and the ChartControl.DrillDownStateChanged event that allows you to customize the chart's diagram with respect to the current data level.

chartControl.DrillDownStateChanged += this.OnChartControlDrillDownStateChanged;
chartControl.DrillDownStateChanging += this.OnChartControlDrillDownStateChanging;

private void OnChartControlDrillDownStateChanging(object sender, DrillDownStateChangingEventArgs e) {
    if (e.States.Length != 0) {
        object categoryValue = null;
        if (e.States.Last().Parameters.TryGetValue("Category", out categoryValue)) {
            int seriesIndex = chartControl.Series.IndexOf(chartControl.Series[(string)categoryValue]);
            int colorIndex = seriesIndex % chartControl.PaletteRepository[chartControl.PaletteName].Count + 1;
            chartControl.PaletteBaseColorNumber = colorIndex;
        }
        if (chartControl.Diagram is XYDiagram diagram) {
            diagram.AxisX.Label.Font = new Font("Tahoma", 8.25f, FontStyle.Regular);
        }
    } else {
        chartControl.PaletteBaseColorNumber = 0;
        if (chartControl.Diagram is XYDiagram diagram) {
            diagram.AxisX.Label.Font = new Font("Tahoma", 8.25f, FontStyle.Underline);
        }
    }
}
private void OnChartControlDrillDownStateChanged(object sender, DrillDownStateChangedEventArgs e) {
    if (!(chartControl.Diagram is XYDiagram diagram)) return;
    if (e.States.Length == 0) {
        diagram.Rotated = true;
        return;
    }
    diagram.Rotated = IsDrillToSeriesFromHome(e.States);
}
private bool IsDrillToSeriesFromHome(DrillDownItem[] drillDownItems) {
    if (drillDownItems.Length != 1) return false;
    IReadOnlyDictionary<string, object> drillDownParams = drillDownItems[0].Parameters;
    if (drillDownParams.Count != 1) return false;
    return drillDownParams.ContainsKey("Category");
}

The following table contains classes and members that allow you to manage the drill down state change.

Symbol Description
ChartControl.DrillDownStateChanging Occurs before the Chart Control's drill down state is changed.
DrillDownStateChangingEventArgs Provides data for the ChartControl.DrillDownStateChanging (WebChartControl.DrillDownStateChanging, or ChartControlSettings.DrillDownStateChanging) event.
ChartControl.DrillDownStateChanged Occurs when the Chart Control's drill down state is changed.
DrillDownStateChangedEventArgs Provides data for the ChartControl.DrillDownStateChanged (WebChartControl.DrillDownStateChanged, or ChartControlSettings.DrillDownStateChanged) event.