DashboardControl's Client-Side API Overview

• Aug 21, 2024
• 3 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.

Configuration

You can configure the control before it is rendered (before the render method call):

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

    dashboardControl.render();
}

Set the Control Option’s Initial Values

The DashboardControlOptions class contains the configuration options. Use the constructor to configure initial settings 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();
}

In the constructor, you can also use the DashboardControlOptions.fetchRemoteService property to access the Fetch-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 () {
    let dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/dashboardControl",
        fetchRemoteService: {
            headers: {
                'Authorization': 'AuthToken123'
            }
        },
    dashboardControl.render();
}

Customize the Control’s Options at Runtime

Use the DashboardControl‘s client API to customize the extension options at runtime.

For example, you can customize the control before it is rendered. The following code removes the “New…” item from the Dashboard Menu:

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

The DashboardControlOptions class contains the configuration options. Call the DashboardControl.option(name, value) method and pass the control option with its new value to update the option at runtime. Pass the option name to the method’s name parameter.

The following code show how to prevent a user from maximizing dashboard items:

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

You cannot call the option method to change values of the following properties at runtime:

• endpoint
• initialDashboardId
• loadDefaultDashboard
• showConfirmationOnBrowserClosing
• useCardLegacyLayout
• mobileLayoutEnabled

These properties are set once before the control is rendered.

Handle Events

You can handle the DashboardControl events in the constructor. The code sample below handles the control’s DashboardControlOptions.onDashboardInitializing event:

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

    dashboardControl.render();
}
function customizeDashboard(args) {
    let dashboardControl = args.component;
    let dashboardId = args.dashboardId;
    // Enables the `allowInspectRawData` option only for the `customers` dashboard:    
    if (dashboardId == "customers") {
        dashboardControl.option("extensions.dataInspector.allowInspectRawData", true);
    } else {
        dashboardControl.option("extensions.dataInspector.allowInspectRawData", false);
    }
}

The method above is only possible if you are sure that there will only be one subscription to the event. For example, when you create and register a custom extension, there may be multiple subscriptions. In this case, it is better to use the control’s on and off methods to subscribe to and unsubscribe from the event. The available event handlers are listed in the DashboardControlEvents type.

The code below subscribes to the same DashboardControlOptions.onDashboardInitializing event as in the example above:

window.onload = function () {
    let dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/dashboardControl",
    });
    dashboardControl.on("dashboardInitializing", customizeDashboard);
    dashboardControl.render();
};
function customizeDashboard(args) {
    // ...
}

An equivalent way is to pass the event handler to the DashboardControl.option(name, value) method call:

window.onload = function () {
    let dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/dashboardControl",
    });
    dashboardControl.option("onDashboardInitializing", customizeDashboard);
    dashboardControl.render();
};
function customizeDashboard(args) {
    // ...
}

You can find available event handlers for the extension in the DashboardControlOptions type.