Working with Extensions

You can use extensions to customize the HTML5 JavaScript Dashboard. The extension is an independent JavaScript module/class that provides specific functionality to the control.

The topic explains how to access the existing extensions, customize them, or create new extensions.

Get Underlying DashboardControl

You can customize the Web Dashboard before the underlying client part is rendered. Use the BeforeRender event to configure the underlying part for wrappers (Web Forms, MVC, and ASP.NET Core controls).

Web Forms and MVC

For Web Forms Dashboard control and MVC Dashboard extension, handle the BeforeRender event to access the Web Dashboard's underlying client part:

<dx:ASPxDashboard ID="ASPxDashboard1" runat="server">
    <ClientSideEvents BeforeRender="onBeforeRender" />
</dx:ASPxDashboard>

Then, call the GetDashboardControl method to get the DashboardControl instance:

<head>
    <script>
        function onBeforeRender(sender) {
            var dashboardControl = sender.GetDashboardControl();
            // Here you can customize a control.
        }
    </script>
</head>

.NET Core

You do not need to call a specific method for the ASP.NET Core MVC control. Handle the BeforeRender event:

@(Html.DevExpress().Dashboard()
    .Name("dashboardControl")
    .Width("100%")
    .Height("100%")
    .OnBeforeRender("onBeforeRender")
) 

The sender is the Web Dashboard's underlying client part:

<head>
    <script>
        function onBeforeRender(sender) {
            var dashboardControl = sender;
            // Here you can customize a control.
        }
    </script>
</head>

After these steps, you can use the DashboardControl instance without wrappers.

HTML5 JavaScript Control

For the HTML5 JavaScript control, configure the control before you call the render method:

window.onload = function () {
    var dashboardControl = = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
        // Here you configure the control's options.
    });    
    // Here you can customize a control.

    dashboardControl.render();
}

Add or Remove Existing Extensions

To access all the enabled extensions, use the DashboardControl.extensions property that returns an array of objects. Each object implements the IExtension interface. The table below lists the Web Dashboard's commonly used extensions:

Extension

Description

ToolboxExtension

The Web Dashboard Toolbox extension that provides access to the dashboard menu and allows you to add dashboard items, as well as undo or repeat user actions.

DashboardParameterDialogExtension

A Web Dashboard extension that is the Dashboard Parameters dialog.

DashboardExportExtension

A Web Dashboard extension that allows you to export dashboards and dashboard items.

ViewerApiExtension

An extension that allows you to customize a visual part of the Web Dashboard.

MobileLayoutExtension

A Web Dashboard extension that allows you to enable a mobile layout for phones.

Each extension exposes the IExtension.name property which returns an extension's unique name. Use this name to access the extension.

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

function onBeforeRender(sender) {
    // ...
    var dashboardControl = sender.GetDashboardControl();
    dashboardControl.unregisterExtension("dashboard-export");
}

Note that some extensions (for instance, DashboardPanelExtension) are disabled. The code below shows how to enable the Dashboard Panel using the DashboardControl.registerExtension method:

function onBeforeRender(sender) {
    // ...
    var dashboardControl = sender.GetDashboardControl();
    dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl));
}

Customize Existing Extension

To configure the registered extension, use the DashboardControl.findExtension method and pass the IExtension.name property value as a method parameter to obtain its instance.

The code sample below demonstrates how to use the ToolboxExtension.removeMenuItem method to obtain the ToolboxExtension and remove the New... command from the dashboard menu:

function onBeforeRender(sender) {
    var dashboardControl = sender.GetDashboardControl();
    var toolboxExtension = dashboardControl.findExtension("toolbox");
    toolboxExtension.removeMenuItem("create-dashboard");
}

Example: How to Add Custom Functionality using Extensions

This example demonstrates how to add the "Save As" and "Delete" menu items to the Web Dashboard's UI by implementing the corresponding custom extensions:

  • The "Save As" menu item allows end-users to save the current dashboard with a new name.
  • The "Delete" menu item deletes the opened dashboard from the dashboard storage.

The image below shows the result of the extensions implementation.

wdd-custom-extension-save-as.png

Imports Storages
Imports System
Imports System.Collections.Generic
Imports System.Web.Script.Serialization

Namespace AspDashboard_CustomExtension
    Partial Public Class [Default]
        Inherits System.Web.UI.Page

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

        End Sub

        Protected Sub ASPxDashboard1_CustomDataCallback(ByVal sender As Object, ByVal e As DevExpress.Web.CustomDataCallbackEventArgs)
            Dim parameters As Dictionary(Of String, String) = (New JavaScriptSerializer()).Deserialize(Of Dictionary(Of String, String))(e.Parameter)
            If Not parameters.ContainsKey("ExtensionName") Then
                Return
            End If

            Dim newDashboardStorage As New CustomDashboardFileStorage("~/App_Data/Dashboards")
            If parameters("ExtensionName") = "dxdde-delete-dashboard" AndAlso parameters.ContainsKey("DashboardID") Then
                newDashboardStorage.DeleteDashboard(parameters("DashboardID"))
            End If
        End Sub
    End Class
End Namespace

See Also