Access to Underlying Widgets

• Aug 03, 2020
• 3 minutes to read

The Web Dashboard control uses DevExtreme widgets to visualize dashboard items’ data. You can access these widgets and customize their settings to add specific capabilities.

The ASPxClientDashboard exposes the following events that allow you to access these widgets and customize their settings:

• The ASPxClientDashboard.ItemWidgetCreated event is raised once for each widget when the dashboard is loaded to client. Handle this event to subscribe to events of the underlying widget.

• ASPxClientDashboard.ItemWidgetUpdating/ASPxClientDashboard.ItemWidgetUpdated events are raised when the client widget needs to be updated. For instance, this can be when you apply a master filter or change parameter values.

  Handle the ASPxClientDashboard.ItemWidgetUpdating event to unsubscribe from the client widget’s events. The ASPxClientDashboard.ItemWidgetUpdated event is used to customize widgets. This allows you to prevent the ASPxClientDashboard from rewriting customized options.

The ASPxClientDashboardItemWidgetEventArgs.ItemName event parameter returns the name of the dashboard item whose widget can be customized. Use the ASPxClientDashboardItemWidgetEventArgs.GetWidget method to access the corresponding underlying widget.

The following table lists dashboard items whose underlying widgets can be accessed when you handle the ItemWidget… events:

Dashboard Item	Underlying Widget(s)
GridItem	dxDataGrid
ChartItem ScatterChartItem	dxChart
PieItem	an array of dxPieChart widgets
GaugeItem	an array of dxCircularGauge or dxLinearGauge widgets
MapItem	dxVectorMap
PivotItem	dxPivotGrid
ComboBoxItem	dxSelectBox or dxTagBox
ListBoxItem	dxList
TreeViewItem	dxTreeList dxTreeView (for v17.1 and earlier)
TreemapItem	dxTreeMap
RangeFilterItem	dxRangeSelector
CardItem	CardWidget
DateFilterItem	DateFilterWidget
TextBoxItem	n/a See Note 1
ImageItem	n/a See Note 1
CustomItem	n/a See Note 2

¹ The content of the TextBoxDashboardItem and the ImageDashboardItem is an HTML element wrapped in a jQuery object.

² The CustomDashboardItem is a custom widget. You can customize it directly.

Limitations

Do not change the following settings to avoid possible issues:

• data binding settings;
• basic data presentation settings (for instance, a set of grid columns or chart series).

Note that changes made with the ItemWidget… events do not change the dashboard/dashboard items’ appearance in exported documents.

Example

This example demonstrates how to customize client widgets used to visualize data within dashboard items at runtime using ASPxClientDashboard‘s API.

The following options are changed:

• The hovered grid row is highlighted in the underlying dxDataGrid in the ItemWidgetCreated event handler.
• A standard tooltip in the dxChart‘s series point is disabled. Click the required label on the argument axis to invoke a tooltip. The ItemWidgetUpdated and ItemWidgetUpdating event are used to subscribe and unsubscribe to/from the argumentAxisClick event.
• A pie legend is shown for the underlying dxPieChart.

Index.cshtml

@Html.DevExpress().Dashboard(settings => {
    settings.Name = "Dashboard";
    settings.Width = Unit.Percentage(100);
    settings.Height = Unit.Percentage(100);
    settings.WorkingMode = DevExpress.DashboardWeb.WorkingMode.ViewerOnly;
    settings.ClientSideEvents.ItemWidgetCreated = "function(s, e) { customizeWidgets(s, e); }";
    settings.ClientSideEvents.ItemWidgetUpdated = "function(s, e) { customizeWidgets(s, e); }";
    settings.ClientSideEvents.ItemWidgetUpdating = "function(s, e) { unsubscribeFromEvents(s, e); }";
}).GetHtml()
<script src="~/Scripts/WidgetCustomization.js"></script>

WidgetCustomization.js

function customizeWidgets(sender, args) {
    if (args.ItemName == "gridDashboardItem1") {
        var grid = args.GetWidget();
        grid.option({
            hoverStateEnabled: true
        });
    }
    if (args.ItemName == "chartDashboardItem1") {
        var chart = args.GetWidget();
        chart.option({
            tooltip: {
                enabled: false
            },
            onArgumentAxisClick: function (info) {
                info.component.getAllSeries()[0].getPointsByArg(info.argument)[0].showTooltip();
            }
        });
    }
    if (args.ItemName == "pieDashboardItem1") {
        var pie = args.GetWidget()[0];
        pie.option({
            legend: {
                visible: true,
                border: {
                    visible: true
                }
            }
        });
    }
}

function unsubscribeFromEvents(sender, args) {
    if (args.ItemName == "chartDashboardItem1") {
        var chart = args.GetWidget();
        chart.option({
            onArgumentAxisClick: undefined
        });
    }
}