Access to Underlying Widgets in ASP.NET Web Forms

Feb 27, 2023
3 minutes to read

Tip

This topic shows the ASP.NET Web Forms specifics. The main widget customization concepts are described in the following article: Access to Underlying Widgets in DashboardControl.

Most dashboard items use DevExtreme UI widgets to visualize data. Use the DashboardControl‘s API to access these widgets and customize their settings. In ASP.NET Web Forms, you need to subscribe to the ViewerApiExtension events that allow you to access underlying UI/Data Visualization widgets. For this, handle the ASPxClientDashboard.BeforeRender client-side event, call the ViewerApiExtension.on method and pass the event name as the method’s parameter.
Several dashboard items use built-in components instead of DevExtreme-based UI widgets.
Layout items do not have underlying components.

See the table in the following topic for information about dashboard items and their underlying components: Access to Underlying Widgets in DashboardControl.

Example

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

The hovered grid row is highlighted in the underlying dxDataGrid.
A standard tooltip that appears when a user hovers over a chart’s series point is disabled.
A custom tooltip appears when a user clicks a label on the chart’s argument axis. The onArgumentAxisClick property executes a function that invokes the custom tooltip.
The animation is enabled for the dxChart and dxPieChart UI components.
The dxPieChart UI component displays a legend.
The font weight and an interval between major ticks are modified in the dxCircularGauge UI component.

View Example

Default.aspx (C#)
Default.aspx (VB.NET)

aspx

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" 
    Inherits="ASPxDashboard_UnderlyingWidgets.Default" %>

<%@ Register Assembly="DevExpress.Dashboard.v24.2.Web.WebForms, Version=24.2.13.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Web Dashboard</title>
    <script src="Scripts/WidgetsCustomization.js"></script>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            WorkingMode="Viewer"
            Height="100%" Width="100%">
            <ClientSideEvents BeforeRender="onBeforeRender" />  
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

aspx

<%@ Page Language="vb" AutoEventWireup="true" CodeBehind="Default.aspx.vb" 
    Inherits="ASPxDashboard_UnderlyingWidgets.Default" %>

<%@ Register Assembly="DevExpress.Dashboard.v24.2.Web.WebForms, Version=24.2.13.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Web Dashboard</title>
    <script src="Scripts/WidgetsCustomization.js"></script>
</head>
<body>
    <form id="form1" runat="server">
    <div style="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            WorkingMode="Viewer"
            Height="100%" Width="100%">
            <ClientSideEvents BeforeRender="onBeforeRender" />  
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

The following code snippet shows how to get underlying data on the client:

WidgetsCustomization.js

function onBeforeRender(s, e) {
    var dashboardControl = s.GetDashboardControl();
    var viewerApiExtension = dashboardControl.findExtension('viewerApi');
    if (viewerApiExtension) {
        viewerApiExtension.on('itemWidgetOptionsPrepared', customizeWidgetOptions);
        viewerApiExtension.on('itemWidgetUpdated', customizeWidget);
        viewerApiExtension.on('itemWidgetCreated', customizeWidget);
    };
}
function customizeWidgetOptions(e) {
    if (e.dashboardItem instanceof DevExpress.Dashboard.Model.GridItem) {
        e.options.hoverStateEnabled = true
    };
    if (e.dashboardItem instanceof DevExpress.Dashboard.Model.ChartItem) {
        e.options.tooltip.enabled = false;
        e.options.animation = {
            ...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 DevExpress.Dashboard.Model.PieItem) {
        e.options.legend = {
            ...e.options.legend,
            visible: true,
            border: {
                ...e.options.legend.border,
                visible: true
            }
        };
        e.options.animation = {
            ...e.options.animation,
            enabled: true,
            duration: 1000
        };
    }
    if (e.dashboardItem instanceof DevExpress.Dashboard.Model.GaugeItem) {
        var gaugesCollection = e.dashboardItem.gauges();
        gaugesCollection.forEach(element => {
            if (element.actualValue().dataMember() == 'Extended Price') {
                e.options.scale.tick.tickInterval = 1000
            }
        });
    }
}
function customizeWidget(e) {
    if (e.dashboardItem instanceof DevExpress.Dashboard.Model.GaugeItem) {
        var gaugesCollection = e.getWidget();
        gaugesCollection.forEach(element => {
            element.option('scale.label.font.weight', '600');            
        });
    }
}