Access to Underlying Widgets

  • 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

OK

ChartItem

ScatterChartItem

dxChart

dxChartOptions

OK

PieItem

an array of dxPieChart widgets

dxPieChartOptions (for each pie)

OK

GaugeItem

an array of dxCircularGauge or dxLinearGauge widgets

dxCircularGaugeOptions or dxLinearGaugeOptions (for each gauge)

OK

ChoroplethMapItem

GeoPointMapItem

PieMapItem

BubbleMapItem

dxVectorMap

dxVectorMapOptions

OK

PivotItem

dxPivotGrid

dxPivotGridOptions

OK

ComboBoxItem

dxSelectBox

dxTagBox

dxSelectBoxOptions

dxTagBoxOptions

OK

ListBoxItem

dxList

dxListOptions

OK

TreeViewItem

dxTreeList

dxTreeView (for v17.1 and earlier)

dxTreeListOptions

dxTreeViewOptions (for v17.1 and earlier)

OK

TreemapItem

dxTreeMap

dxTreeMapOptions

OK

RangeFilterItem

dxRangeSelector

dxRangeSelectorOptions

OK

Dashboard Build-in Components

CardItem

CardWidget

Not Supported

OK

DateFilterItem

DateFilterWidget

Not Supported

OK

TextBoxItem

HTML element / HTML element wrapped in a jQuery object

Not Supported

OK

ImageItem

HTML element / HTML element wrapped in a jQuery object

Not Supported

OK

BoundImageItem

HTML element / HTML element wrapped in a jQuery object

Not Supported

OK

CustomItem

A custom widget. You can customize it directly.

Not Supported

OK

Layout Items

GroupItem

Not Supported

Not Supported

OK

DashboardTabPage

Not Supported

Not Supported

OK

TabContainerItem

Not Supported

Not Supported

Not Supported

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:

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