Access to Underlying Widgets

• Jan 25, 2021
• 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 DashboardControl exposes the following members that allow you to access these widgets and customize their settings:

Event	Description
ViewerApiExtensionOptions.onItemWidgetOptionsPrepared	Occurs before the widget is prepared. Handle this event to configure DevExtreme widgets before they are rendered.
ViewerApiExtensionOptions.onItemWidgetCreated	Occurs once for each widget when the dashboard is loaded to the client. Handle this event to subscribe to the underlying widget’s events.
ViewerApiExtensionOptions.onItemWidgetUpdated ViewerApiExtensionOptions.onItemWidgetUpdating	Occurs when widget should be updated. For instance, when you apply filters or change parameter values.

The DashboardItemBaseEventArgs.itemName property returns the component name of the dashboard item whose widget can be customized. Use the ItemWidgetEventArgs.getWidget property 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	onItemWidgetCreated/onItemWidgetUpdated	onItemWidgetOptionsPrepared	onItemCaptionToolbarUpdated
DevExtreme-based Widgets
GridItem	dxDataGrid	dxDataGridOptions
ChartItem ScatterChartItem	dxChart	dxChartOptions
PieItem	an array of dxPieChart widgets	dxPieChartOptions (for each pie)
GaugeItem	an array of dxCircularGauge or dxLinearGauge widgets	dxCircularGaugeOptions or dxLinearGaugeOptions (for each gauge)
ChoroplethMapItem GeoPointMapItem PieMapItem BubbleMapItem	dxVectorMap	dxVectorMapOptions
PivotItem	dxPivotGrid	dxPivotGridOptions
ComboBoxItem	dxSelectBox dxTagBox	dxSelectBoxOptions dxTagBoxOptions
ListBoxItem	dxList	dxListOptions
TreeViewItem	dxTreeList dxTreeView (for v17.1 and earlier)	dxTreeListOptions dxTreeViewOptions (for v17.1 and earlier)
TreemapItem	dxTreeMap	dxTreeMapOptions
RangeFilterItem	dxRangeSelector	dxRangeSelectorOptions
Dashboard Build-in Components
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 widget. You can customize it directly.
Layout Items
GroupItem
DashboardTabPage
TabContainerItem

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

The following code snippets show how to customize client widgets used to visualize data within dashboard items at runtime on the client side.

The changed options are listed below:

• The hovered grid row is highlighted in the underlying dxDataGrid in the ViewerApiExtensionOptions.onItemWidgetCreated event handler.
• A standard tooltip that is invoked over a chart series point is disabled. You need to click the required label on the argument axis to invoke a tooltip. The argumentAxisClick event is used to change the behavior. Subscription and unsubscription to/from the argumentAxisClick event are performed in the ViewerApiExtensionOptions.onItemWidgetUpdated and ViewerApiExtensionOptions.onItemWidgetUpdating event handlers, respectively.
• A pie legend is shown for the underlying dxPieChart.

dashboard.component.ts

// ...
var dashboardControl = new DashboardControl(this.element.nativeElement.querySelector(".dashboard-container"),  {  
    endpoint: "https://demos.devexpress.com/services/dashboard/api",
    workingMode: "Designer",
    extensions: {
        "viewerApi": {
            onItemWidgetUpdated: "function(args) { customizeWidgets(args); }",
            onItemWidgetCreated: "function(args) { customizeWidgets(args); }",
            onItemWidgetUpdating: "function(args) { unsubscribeFromEvents(args); }"
        }
    }
});

widgets.customization.js

function customizeWidgets(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(args) {
    if (args.ItemName == "chartDashboardItem1") {
        var chart = args.GetWidget();
        chart.option({
            onArgumentAxisClick: undefined
        });
    }
}