Manage Extensions in the JavaScript Dashboard Control
- 5 minutes to read
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.
You can use the DashboardControlOptions.extensions property to access registered extension settings.
Set the Extension Option’s Initial Values
Set the initial values of the extension options in the DashboardControl‘s constructor. The following code changes the DataInspectorExtension options to enable the Data Inspector:
window.onload = function () {
let dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/dashboardControl",
extensions: {
'dataInspector': {
allowInspectAggregatedData: true,
allowInspectRawData: true
},
'dashboardExport': {
allowExportDashboardItems: false
}
}
});
dashboardControl.render();
}
Customize the Extension’s Options at Runtime
Use the DashboardControl‘s client API to customize the extension options at runtime.
Call the DashboardControl.option(name, value) method and pass the extension option with its new value to update the option at runtime. Follow the extensions.extensionName.optionName pattern when you pass the option name to the method’s name parameter. The available extension’s options you can find in the ...ExtensionOptions types (for example, DataInspectorExtensionOptions).
The following code shows how to enable the Data Inspector depending on the dashboardId. The customizeDashboard function is called in the onDashboardInitializing event handler:
function customizeDashboard(args) {
let dashboardControl = args.component;
let dashboardId = args.dashboardId;
// Enable the Data Inspector depending on a dashboard identifier.
if (dashboardId === "dashboard1") {
dashboardControl.option("extensions.dataInspector.allowInspectRawData", true);
} else {
dashboardControl.option("extensions.dataInspector.allowInspectRawData", false);
}
}
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 the Extension’s Events
Find the extension by its name and pass the extension’s event handler name to the extension’s on/off methods to subscribe/unsubscribe on the the extension events. Refer to the ...ExtensionEvents types to get available event handlers for the extension (for example, ViewerApiExtensionEvents).
This example shows how to handle the ViewerApiExtensionOptions.onItemCaptionToolbarUpdated and ViewerApiExtensionOptions.onDashboardTitleToolbarUpdated events. The code below calls the customizeCaptionToolbar and customizeTitleToolbar custom functions:
window.onload = function () {
let dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/dashboardControl"
});
// Find the ViewerApiExtension instance.
let viewerApiExtension = dashboardControl.findExtension("viewerApi");
if (viewerApiExtension) {
// Pass the ViewerApiExtension's handlers to the ViewerApiExtension's "on" method.
viewerApiExtension.on('itemCaptionToolbarUpdated', customizeCaptionToolbar);
viewerApiExtension.on('dashboardTitleToolbarUpdated', customizeTitleToolbar);
}
dashboardControl.render();
}
An equivalent way is to pass the extension handler to the DashboardControl.option(name, value) method call. Follow the extensions.extensionName.eventHandlerName pattern when you pass the event handler to the method’s name parameter. You can find available event handlers for the extension in the ...ExtensionOptions types (for example, DashboardExportExtensionOptions).
The example shows how to handle the ViewerApiExtensionOptions.onItemCaptionToolbarUpdated and ViewerApiExtensionOptions.onDashboardTitleToolbarUpdated events. The following subscriptions call the same customizeCaptionToolbar and customizeTitleToolbar custom functions as in the example above:
window.onload = function () {
let dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/dashboardControl"
});
// Pass the ViewerApiExtension's handlers to the control's "option" method.
dashboardControl.option("extensions.viewerApi.onItemCaptionToolbarUpdated", customizeCaptionToolbar);
dashboardControl.option("extensions.viewerApi.onDashboardTitleToolbarUpdated", customizeTitleToolbar);
dashboardControl.render();
}
Remove an Extension
You can unregister the extension to remove the specific functionality from the Web Dashboard. For example, you can completely remove the export functionality if you unregister the DashboardExportExtension.
To remove the registered extension, call the DashboardControl.unregisterExtension method and pass the extension unique name as a parameter. The following code unregisters the CreateDashboardExtension and removes the ‘New…’ item from the dashboard menu:
window.onload = function () {
let dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/dashboardControl"
});
dashboardControl.unregisterExtension("createDashboard");
dashboardControl.render();
}
Register a New Extension
Add the extension script on the page after the DashboardControl‘s scripts. Register an extension before the control’s render method. Pass the extension instance as the control’s registerExtension method parameter.
The code below registers the integrated DashboardPanelExtension and the HelloWorld custom item from the external HelloWorldItem.js file:
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width" />
<title>Dashboard Web Application</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<!-- ... -->
<script src="node_modules/devexpress-dashboard/dist/js/dx-dashboard.min.js"></script>
<script src="Scripts/HelloWorldItem.js"></script>
<script>
window.onload = function () {
var dashboardControl = new DevExpress.Dashboard.DashboardControl(document.getElementById("web-dashboard"), {
endpoint: "/dashboardControl"
});
dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl, { dashboardThumbnail: "./Content/DashboardThumbnail/{0}.png" }));
dashboardControl.registerExtension(new HelloWorldCustomItem(dashboardControl));
dashboardControl.render();
};
</script>
</head>
<body>
<div id="web-dashboard" style="position: absolute; left: 0; right: 0; top: 0; bottom: 0"></div>
</body>
</html>
More Examples
The following topic describes how to register the TextBoxItemEditorExtension: Enable Text Editor Functionality.
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.