Access to Underlying Widgets in DashboardControl

  • 4 minutes to read

The Web Dashboard control uses widgets and components to visualize data inside dashboard items.

Most dashboard items use DevExtreme UI widgets 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:

  1. The Web Dashboard loads the widget’s default configuration.

    The onItemWidgetOptionsPrepared event is raised. Handle this event to customize the DevExtreme widget’s options before the widget is rendered.

  2. The Web Dashboard renders the widget with the configured options.

    The onItemWidgetCreated event is raised. It occurs once for each widget when the dashboard is loaded to the client. You can use this event to customize the widget instance. Use the ViewerApiExtension.on and ViewerApiExtension.off methods to subscribe to and unsubscribe from the widget’s events.

  3. The widget is updated (for example, when you apply filters or change parameter values).

    The onItemWidgetUpdated event is raised. It occurs every time the widget should be re-rendered. Use the ViewerApiExtension.on and ViewerApiExtension.off methods to subscribe to and unsubscribe from the DevExtreme widget’s events.

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:

The following table lists dashboard items whose DevExtreme UI widgets can be accessed when you handle the ItemWidget… events.

Dashboard Items onItemWidgetCreated/onItemWidgetUpdated onItemWidgetOptionsPrepared
GridItem dxDataGrid dxDataGridOptions
ChartItem
ScatterChartItem
dxChart dxChartOptions
PieItem an array of dxPieChart components dxPieChartOptions (for each pie)
GaugeItem an array of dxCircularGauge or dxLinearGauge components 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

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 Not Supported
DateFilterItem DateFilterWidget Not Supported
TextBoxItem HTML element / HTML element wrapped in a jQuery object Not Supported
ImageItem HTML element / HTML element wrapped in a jQuery object Not Supported
BoundImageItem HTML element / HTML element wrapped in a jQuery object Not Supported
CustomItem A custom component that you can customize directly. Not Supported

Note

Layout items do not have underlying components, so you cannot customize them with the onItemWidget... events:

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 or dashboard item appearance in exported documents.

Example

The example shows how to customize options of underlying widgets. Handle the onItemWidgetOptionsPrepared event to do the following:

  • Highlight a hovered grid row in the underlying dxDataGrid.
  • Disable a standard tooltip that appears when a user hovers over a chart’s series point.
  • Create a custom tooltip that appears when a user clicks a label on the chart’s argument axis. The onArgumentAxisClick property executes a function that invokes the custom tooltip.
  • Enable the animation for the dxChart and dxPieChart widgets.
  • Display a legend in the dxPieChart widget.

View Example

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
    };
  }
}