Extensions in the Web Dashboard

• Apr 21, 2023
• 3 minutes to read

This topic explains what is an extension, how to access existing extensions, and how to customize them.

What is an Extension

You can access extensions to customize the Web Dashboard control. The extension is an independent JavaScript module/class that adds specific functionality to the control. Each extension implements the IExtension interface. For example, the DashboardExportExtension enables users to export dashboard data, the DashboardParameterDialogExtension manages dashboard parameters, and the ToolboxExtension allows you to customize the Toolbox. If you disable the extension, the functionality this extension provides is unavailable.

View the DevExpress.Dashboard.Designer module to find extensions used in the Web Dashboard when it operates as a designer. The DevExpress.Dashboard contains extensions used both in Designer and Viewer modes. You can use the DashboardControl.extensions property to get an array of registered extensions you can customize.

What You Need to Access Extensions

You can customize the Web Dashboard before the underlying control is rendered. To do this, you need to access the DashboardControl instance: Web Dashboard Technical Overview - Client-Side Specifics.

Customize Existing Extension

Each extension exposes the IExtension.name property that returns an extension’s unique name. You can use this name to access the extension.

To configure the registered extension, you need to obtain its instance. For this, call the DashboardControl.findExtension method and pass the name property value as a method parameter.

The code sample below demonstrates how to remove the New… command from the dashboard menu (ToolboxExtension). To do this, call the extension’s removeMenuItem method:

function onBeforeRender(sender) {
    // ...
    // The dashboardControl variable is the obtained DashboardControl instance.
    var toolboxExtension = dashboardControl.findExtension("toolbox");
    toolboxExtension.removeMenuItem("create-dashboard");
}

The ViewerApiExtension instance is used to customize the Web Dashboard’s visual components. The image below shows a custom button in the dashboard title:

You can modify the following visual components with the ViewerApiExtension‘s events:

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

Enable or Disable Existing Extensions

To disable an extension, pass its name to the DashboardControl.unregisterExtension method. The code below shows how to disable the Web Dashboard’s export functionality:

function onBeforeRender(sender) {
    // ...
    // The dashboardControl variable is the obtained DashboardControl instance.
    dashboardControl.unregisterExtension("dashboardExport");
}

Some extensions (for instance, DashboardPanelExtension) are disabled, but their code already exists in the Web Dashboard application. Call the DashboardControl.registerExtension method to enable such extensions:

// The dashboardControl variable is the obtained DashboardControl instance.
dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl));

Create and Register a New Extension

Besides the integrated extensions, you can write a custom script and register it in a Web Dashboard component to extend the Web Dashboard functionality. It can be new buttons with custom functions in the dashboard menu, custom properties for existing dashboard items, and even new custom dashboard items.

You can add an additional functionality to the Web Dashboard component with a few steps:

1. Create an extension.
2. Attach its code to a page containing the Web Dashboard component.
3. Register this extension in the Web Dashboard component.

See the following topic for details: Create Custom Extensions in the Web Dashboard.