Client-Side Customization

The DashboardControl allows you to configure the control's view and capabilities and provides different ways to customize the dashboard control on the client side:

DashboardControl Options

The DashboardControlOptions class contains the DashboardControl's configuration options. You can configure the DashboardControl's options in the control's constructor. The code snippet below shows how to specify several options when creating the DashboardControl:

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

You can use the control's events to customize the Web Dashboard. The following code shows how to handle the DashboardInitializing event:

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

Model

The Dashboard.Model module contains classes and members that comprise the Dashboard object model. This module provides an API to perform the actions available for end-users in client UI. You can create or update dashboard items and the entire dashboard, manage format rules, change item's layout, add dashboard parameters, etc.

For example, the Dashboard class contains a complete description of a dashboard, including the collection of dashboard items and groups, data binding information, layout and appearance settings. You can add dashboard parameters (Dashboard.parameters), change dashboard title settings (Dashboard.title), customize a global color scheme (Dashboard.colorScheme), etc.

The DashboardItem descendants allow you to create a dashboard item on the client side, configure it and bind it to data.

The following code sample shows how to add the tab container with two tab pages:

var tabContainer1 = new DevExpress.Dashboard.Model.TabContainerItem();
tabContainer1.tabPages()[0].name("Difference");

var page2 = new DevExpress.Dashboard.Model.DashboardTabPage();
page2.name("Sales");

tabContainer1.tabPages.push(page2);

dashboardControl.dashboard().items.push(tabContainer1);

dashboardControl.dashboard().rebuildLayout();

Extensions

The DashboardControl allows you to manage the Web Dashboard's functionality using independent JavaScript modules/classes called extensions. For example, the DashboardExportExtension enables end-users to export the dashboard's data, the DashboardParameterDialogExtension adds dashboard parameters, and the ToolboxExtension allows you to customize the Toolbox.

You can use the DashboardControlOptions.extensions property to access registered extensions' settings in the DashboardControl's constructor. The code sample below shows how to use the DashboardExportExtensionOptions to specify the control's export settings:

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

The other way to configure the registered extension is to use the DashboardControl.findExtension method to obtain the extension's instance and pass the IExtension.name property value as a method parameter. Use the DashboardControl.extensions property to access all the enabled extensions. For instance, the code below uses the ToolboxExtension.removeMenuItem method to remove the New... command 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");
}

The ViewerApiExtension class contains events you can use to customize the Web Dashboard's visual components. For example, you can add a custom button to the dashboard title:

Custom Button in the Dashboard Title

The image below shows the Web Dashboard's visual components you can modify:

  1. Dashboard menu
  2. Toolbox
  3. Toolbar
  4. Dashboard title
  5. Dashboard item caption
  6. Dashboard item menu

Visual Components Customization

The code sample below shows how to handle the ItemCaptionToolbarUpdated event and add a custom button to the Chart's dashboard item caption:

window.onload = function () {
    var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        endpoint: "/api/dashboard",   
        onItemBeginUpdate: function(e) {
            // ...
        },
        extension: {
            'viewer-api': {
                onItemCaptionToolbarUpdated: function (e) {
                    if (e.itemName === "chartDashboardItem1") {
                        e.options.actionItems.push({
                            type: "button",
                            text: "Custom Button",
                            click: function () {
                                // ...
                            }
                        });
                    }
                }
            }
        },
    });
}

See Extending Web Dashboard Functionality to learn how to add, remove or configure the Web Dashboard's extensions.

Custom Extensions

You can create a separate extension that adds some specific functionality to the Web Dashboard. For instance, the extension can allow you to save a dashboard with a different name, delete the opened dashboard, modify the Dashboard Parameter window, etc.

Save_As_Extension

Use the DashboardControl.registerExtension method to register the created extension in the Web Dashboard.

Refer to Extensions on GitHub to see custom extension examples you can use in your Web Dashboard application.

Custom Items

A custom item is a complex extension that acts as a dashboard item. You can use the DevExtreme widgets or third-party JavaScript libraries to create additional dashboard items (for example, the d3-funnel library is used to create the FunnelD3 custom item).

CustomItem_Funnel_Main

Use the DashboardControl.registerExtension method to add the custom item to the Web Dashboard.

The Creating a Custom Item section contains detailed information related to a custom item.

See Also