DashboardControl's Client-Side API Overview

• Apr 05, 2021
• 2 minutes to read

The Web Dashboard is a client-server control. On the client side, the Web Dashboard utilizes the DashboardControl to supply users with a UI to design and interact with a dashboard. You can use its API to specify settings on the client and send requests to the server.

You can configure the control before it is rendered:

window.onload = function () {
    var dashboardControl = = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        // Configure the control's options here:
    });    
    // Customize the control here:

    dashboardControl.render();
}

Configuration

Use the DashboardControlOptions properties to customize the control. The DashboardControlOptions class contains the configuration options you can configure in the control’s constructor before the control is initialized:

window.onload = function () {
    var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/api/dashboard",
        workingMode: "ViewerOnly",
        initialDashboardId: "dashboard1"
    });

    dashboardControl.render();
}

You can use the DashboardControlOptions.extensions property to access registered extension settings in the DashboardControl‘s constructor. The code sample below shows how to configure DashboardExportExtensionOptions to disable export and customize the dashboard item caption:

window.onload = function () {
    var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/api/dashboard",
        extensions: {
            'dashboardExport': {
                allowExportDashboard: false,
                allowExportDashboardItems: false
            },
            'viewerApi': {
                onItemCaptionToolbarUpdated: function (e) {
                    if (e.itemName === "chartDashboardItem1") {
                        e.options.actionItems.push({
                            type: "button",
                            text: "Custom Button",
                            click: function () {
                                alert("The item name is " + e.itemName);
                            }
                        });
                    }
                }
            }
        },
    }

    dashboardControl.render();
}

In the constructor, you can also use the DashboardControlOptions.ajaxRemoteService property to access the Ajax-based remote service used to communicate with the server side. The following code sets the server’s URL and passes a custom Authorization header from the client:

window.onload = function () {
    var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "{baseURL}/api/dashboard",
        ajaxRemoteService: {
            headers: {
                'Authorization': 'AuthToken123'
            }
        }
    });
}

You can handle events when you configure the control’s options. The code sample below handles the control’s ItemCaptionToolbarUpdated event:

window.onload = function () {
    var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/api/dashboard",   
        onItemCaptionToolbarUpdated: function(e) {
            // ...
        }
    });

    dashboardControl.render();
}

Customization

Use the DashboardControl options to customize the control.

For example, you can customize the registered extension. For this, use the DashboardControl.findExtension method to obtain its instance and pass the IExtension.name property value as a method parameter.

window.onload = function () {
    var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/api/dashboard"
    });

    var toolboxExtension = dashboardControl.findExtension("toolbox");
    toolboxExtension.removeMenuItem("create-dashboard");

    dashboardControl.render();
}

More information: Extensions Overview.