Manage Extensions in ASP.NET Web Forms
- 4 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.
Configure an Extension
Set the Extension Option’s Initial Values
The ASPxDashboard class contains properties you can use to configure the registered extensions and their initial settings. The code below sets the ASPxDashboard.AllowInspectAggregatedData and ASPxDashboard.AllowExportDashboard properties:
<dx:ASPxDashboard ID="ASPxDashboard1" runat="server"
Width="100%"
Height="100%"
AllowExportDashboard="true"
AllowInspectAggregatedData="true"
WorkingMode="Viewer">
</dx:ASPxDashboard>
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:
function onDashboardInitializing(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);
}
}
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).
In this example, a new button is added to the dashboard item caption and displays the item’s componentName when you click on this button:
function onBeforeRender(dashboardControl) {
let viewerApiExtension = dashboardControl.findExtension("viewerApi");
if (viewerApiExtension) {
// Pass the `itemCaptionToolbarUpdated` event handler to the `ViewerApiExtension.on` method call.
viewerApiExtension.on('itemCaptionToolbarUpdated', customizeCaptionToolbar);
}
}
function customizeCaptionToolbar(e) {
e.options.actionItems.push({
type: "button",
text: "Name",
hint: "Show Component Name",
click: function () {
DevExpress.ui.notify("The component name of this dashboard item is " + e.itemName, "info");
}
});
}
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).
This example adds the same button as in the example above:
function onBeforeRender(dashboardControl) {
// Pass the `extensions.viewerApi.onItemCaptionToolbarUpdated` event handler to the `DashboardControl.option` method call.
dashboardControl.option("extensions.viewerApi.onItemCaptionToolbarUpdated", customizeCaptionToolbar);
}
function customizeCaptionToolbar(e) {
e.options.actionItems.push({
type: "button",
text: "Name",
hint: "Show Component Name",
click: function () {
DevExpress.ui.notify("The component name of this dashboard item is " + e.itemName, "info");
}
});
}
Note
See the following topic for more information about the DashboardControl: DashboardControl’s Client-Side API Overview.
Remove an Extension
You can unregister the extension to remove specific functionality from the Web Dashboard. For example, you can remove the export functionality if you unregister the DashboardExportExtension.
To remove the registered extension, handle the BeforeRender event. Use the ASPxClientDashboard.GetDashboardControl method to get the DashboardControl instance. 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:
<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
<script type="text/javascript">
function onBeforeRender(sender) {
var dashboardControl = sender.GetDashboardControl();
dashboardControl.unregisterExtension('createDashboard');
}
</script>
<dx:ASPxDashboard ID="ASPxDashboard1" runat="server" Width="100%" Height="100%">
<ClientSideEvents BeforeRender="onBeforeRender" />
</dx:ASPxDashboard>
</asp:Content>
Register a New Extension
Add the extension script on the page after the ASPxDashboard tag. Register an extension in the BeforeRender event handler. Use the ASPxClientDashboard.GetDashboardControl method to get the DashboardControl instance. 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:
<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
<script type="text/javascript">
function onBeforeRender(sender) {
var dashboardControl = sender.GetDashboardControl();
dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl));
dashboardControl.registerExtension(new HelloWorldCustomItem(dashboardControl));
}
</script>
<dx:ASPxDashboard ID="ASPxDashboard1" runat="server" Width="100%" Height="100%">
<ClientSideEvents BeforeRender="onBeforeRender" />
</dx:ASPxDashboard>
<script src="Scripts/HelloWorldItem.js"></script>
</asp:Content>
More Examples
The following topic describes how to register the TextBoxItemEditorExtension that is disabled by default: Enable Text Editor Functionality.
This example shows how to implement the custom extensions that add the “Save As” and “Delete” menu items to the Web Dashboard’s UI: