dashboard-400996-web-dashboard-advanced-customization-access-to-underlying-widgets.md
The Web Dashboard control uses widgets and UI components to visualize data inside dashboard items.
Most dashboard items use DevExtreme UI Components to visualize data. You can use the DashboardControl API to access these widgets and customize settings you cannot access from the Web Dashboard’s UI.
The Web Dashboard renders an underlying widget as follows:
The Web Dashboard loads the widget’s default configuration.
The Web Dashboard renders the widget with the configured options.
The widget is updated (for example, when you apply filters or change parameter values).
The e.itemName property returns the component name of the dashboard item whose widget can be customized. The e.getWidget property provides access to the corresponding underlying widget.
Note
The e.getWidget property can return an array of widgets for the dashboard items below in case these dashboard items have series:
e.getWidget returns an array of dxPieChart widgets.e.getWidget returns an array of dxCircularGauge or dxLinearGauge widgets.The following table lists dashboard items whose DevExtreme UI widgets can be accessed when you handle the ItemWidget… events.
The dashboard items below use built-in components instead of DevExtreme-based UI widgets. You cannot use the onItemWidgetOptionsPrepared event to customize their options:
| Dashboard Items | onItemWidgetCreated/onItemWidgetUpdated | onItemWidgetOptionsPrepared |
|---|---|---|
| CardItem | CardWidget | |
| DateFilterItem | DateFilterWidget | |
| TextBoxItem | HTML element / HTML element wrapped in a jQuery object | |
| ImageItem | HTML element / HTML element wrapped in a jQuery object | |
| BoundImageItem | HTML element / HTML element wrapped in a jQuery object | |
| CustomItem | A custom component that you can customize directly. |
Note
Layout items do not have underlying components, so you cannot customize them with the onItemWidget... events:
Although the export does not automatically applies custom settings, you can customize the exported document.
The Dashboard Control raises the ASPxDashboard.CustomExport/DashboardConfigurator.CustomExport event before saving the exported document to the PDF and Image formats. The event allows you to customize the exported document.
The following table illustrates dashboard items and their corresponding printable XRControls:
Do not change the following settings to avoid possible issues:
Note that changes made with the ItemWidget… events do not change the dashboard or dashboard item appearance in exported documents.
The example shows how to customize options of underlying widgets. Handle the onItemWidgetOptionsPrepared event to do the following:
import { GridItem, ChartItem, PieItem} from 'devexpress-dashboard/model';
// ...
function customizeWidgetOptions(e) {
if (e.dashboardItem instanceof GridItem) {
e.options.hoverStateEnabled = true
};
if (e.dashboardItem instanceof ChartItem) {
e.options.tooltip = {
enabled: false
};
e.options.animation = {
enabled: true,
duration: 1000
};
e.options.onArgumentAxisClick = function (info) {
info.component.getAllSeries()[0].getPointsByArg(info.argument)[0].showTooltip()
}
};
if (e.dashboardItem instanceof PieItem) {
e.options.legend = {
visible: true,
border: {
visible: true
}
};
e.options.animation = {
enabled: true,
duration: 1000
};
}
}
The following example shows how to customize dashboard items in the exported document when you handle the ASPxDashboard.CustomExport / DashboardConfigurator.CustomExport events. You can use the CustomExportWebEventArgs.GetPrintableControls method to obtain the printable controls.
using DevExpress.DashboardCommon;
using DevExpress.DashboardWeb;
using DevExpress.XtraCharts;
using DevExpress.XtraReports.UI;
using System;
using System.Drawing;
using System.Linq;
protected void CustomizeExport(object sender, CustomExportWebEventArgs e) {
foreach(var printControl in e.GetPrintableControls()) {
if(printControl.Value is XRGaugeDashboardItem) {
var gaugeItemName = printControl.Key;
var gaugeDashboardItem = e.GetDashboardItem(gaugeItemName) as GaugeDashboardItem;
foreach(var dashGaugeElement in gaugeDashboardItem.Gauges) {
foreach(var gaugePanel in e.GetGaugeContext(gaugeItemName).GetPrintableGauges(dashGaugeElement).Cast<XRDashboardGauge>()) {
if(gaugePanel != null) {
gaugePanel.MainSeriesLabel.ForeColor = Color.Red;
}
}
}
}
if(printControl.Value is XRChart) {
var chartItemName = printControl.Key;
var chartDashboardItem = e.GetDashboardItem(chartItemName) as ChartDashboardItem;
foreach(var pane in chartDashboardItem.Panes) {
if(pane.Series.Count > 0) {
foreach(var dashSeries in pane.Series) {
if(dashSeries != null) {
var controlSeries = e.GetChartContext(chartItemName).GetControlSeries(dashSeries);
if(controlSeries != null) {
foreach(var ser in controlSeries) {
LineSeriesView view = ser.View as LineSeriesView;
if(view != null) {
view.LineStyle.DashStyle = DashStyle.DashDot;
}
}
}
}
}
}
}
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWeb
Imports DevExpress.XtraCharts
Imports DevExpress.XtraReports.UI
Imports System
Imports System.Drawing
Imports System.Linq
Protected Sub ASPxDashboard1_CustomExport(ByVal sender As Object, ByVal e As CustomExportWebEventArgs)
For Each printControl In e.GetPrintableControls()
If TypeOf printControl.Value Is XRGaugeDashboardItem Then
Dim gaugeItemName = printControl.Key
Dim gaugeDashboardItem = TryCast(e.GetDashboardItem(gaugeItemName), GaugeDashboardItem)
For Each dashGaugeElement In gaugeDashboardItem.Gauges
For Each gaugePanel In e.GetGaugeContext(gaugeItemName).GetPrintableGauges(dashGaugeElement).Cast(Of XRDashboardGauge)()
If gaugePanel IsNot Nothing Then
gaugePanel.MainSeriesLabel.ForeColor = Color.Red
End If
Next gaugePanel
Next dashGaugeElement
End If
If TypeOf printControl.Value Is XRChart Then
Dim chartItemName = printControl.Key
Dim chartDashboardItem = TryCast(e.GetDashboardItem(chartItemName), ChartDashboardItem)
For Each pane In chartDashboardItem.Panes
If pane.Series.Count > 0 Then
For Each dashSeries In pane.Series
If dashSeries IsNot Nothing Then
Dim controlSeries = e.GetChartContext(chartItemName).GetControlSeries(dashSeries)
If controlSeries IsNot Nothing Then
For Each ser In controlSeries
Dim view As LineSeriesView = TryCast(ser.View, LineSeriesView)
If view IsNot Nothing Then
view.LineStyle.DashStyle = DashStyle.DashDot
End If
Next ser
End If
End If
Next dashSeries
End If
Next pane
End If
Next printControl
End Sub