Migrate from ASPxClientDashboard to DashboardControl API

• Oct 06, 2023
• 5 minutes to read

DashboardControl API is a unified API and an entry point for Web Dashboard customization for all Web Dashboard controls. This API makes it easy to share the JavaScript code between platforms: the code became almost identical for all supported platforms.

The ASPxDashboard control and MVCxDashboard extension have a client-side equivalent called ASPxClientDashboard. It is a wrapper for the DashboardControl with a similar, but limited API.

To migrate to the unified client API in ASP.NET Web Forms and ASP.NET MVC applications, first obtain the DashboardControl instance. You can then use the table in this article to replace the ASPxClientDashboard API calls with the corresponding DashboardControl API.

Tip

See the following topic about the Web Dashboard architecture: Web Dashboard Technical Overview.

Step 1. Obtain the DashboardControl Instance

The ASPxClientDashboard object is a wrapper for DashboardControl. Follow the steps below to get the DashboardControl instance:

1. Handle the ASPxClientDashboard.BeforeRender event.
2. In the event handler, call the ASPxClientDashboard.GetDashboardControl method.

The GetDashboardControl method returns the DashboardControl instance that is common for all supported platforms:

See the following topics for details and event handling examples:

• Client-Side API Overview for ASP.NET Web Forms Dashboard
• Client-Side API Overview for ASP.NET MVC Dashboard

Step 2. Change the ASPxClientDashboard to DashboardControl API

The main difference between the two API versions is the capitalization of the first letter. The ASPxClientDashboard API uses Pascal Case (“OnItemClick”). The DashboardControl API uses Camel Case (“onItemClick”).

DashboardControl - methods and events

Change the API from Pascal Case to Camel Case.

Extensions - methods and events

Call the DashboardControl.findExtension(extensionName) method and pass the extension name as a parameter to obtain the extension instance. Change the API from Pascal Case to Camel Case.

Client events

Handle client events in the onBeforeRender event handler. Call the extension’s on method (for example, ViewerApiExtension.on) and pass the event handler name as a parameter.

Return value and parameter types

Change the ASPxClientDashboard return value and parameter types to the DashboardControl type aliases and classes.

API Reference

Refer to these API lists to find the corresponding members in a unified API when you migrate from the ASPxClientDashboard API.

Interactivity

Common

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.ItemClick	ViewerApiExtensionOptions.onItemClick
ASPxClientDashboard.ActionAvailabilityChanged	ViewerApiExtensionOptions.onItemActionAvailabilityChanged
ASPxClientDashboard.ItemVisualInteractivity	ViewerApiExtensionOptions.onItemVisualInteractivity

How to add custom interactivity to a dashboard:

• ASP.NET Core

How to obtain a dashboard item’s underlying data for a clicked visual element:

• ASP.NET Core
• ASP.NET MVC
• ASP.NET Web Forms

Master Filtering

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.GetCurrentFilterValues(itemName)	ViewerApiExtension.getCurrentFilterValues(itemName)
ASPxClientDashboard.GetCurrentRange(itemName)	ViewerApiExtension.getCurrentRange(itemName)
ASPxClientDashboard.GetAvailableFilterValues(itemName)	ViewerApiExtension.getAvailableFilterValues(itemName)
ASPxClientDashboard.SetRange(itemName, range)	ViewerApiExtension.setRange(itemName, range)
ASPxClientDashboard.CanClearMasterFilter(itemName)	ViewerApiExtension.canClearMasterFilter(itemName)
ASPxClientDashboard.CanSetMasterFilter(itemName)	ViewerApiExtension.canSetMasterFilter(itemName)
ASPxClientDashboard.ClearMasterFilter(itemName)	ViewerApiExtension.clearMasterFilter(itemName)
ASPxClientDashboard.SetMasterFilter(itemName, values)	ViewerApiExtension.setMasterFilter(itemName, values)
ASPxClientDashboard.ItemMasterFilterStateChanged	ViewerApiExtensionOptions.onItemMasterFilterStateChanged

How to apply a master filter on the client:

- [ASP.NET Web Forms](https://github.com/DevExpress-Examples/asp-net-web-forms-dashboard-apply-master-filter-in-code)

Drill-Down

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.GetCurrentDrillDownValues(itemName)	ViewerApiExtension.getCurrentDrillDownValues(itemName)
ASPxClientDashboard.GetAvailableDrillDownValues(itemName)	ViewerApiExtension.getAvailableDrillDownValues(itemName)
ASPxClientDashboard.PerformDrillDown(itemName, value)	ViewerApiExtension.performDrillDown(itemName, value)
ASPxClientDashboard.PerformDrillUp(itemName)	ViewerApiExtension.performDrillUp(itemName)
ASPxClientDashboard.CanPerformDrillDown(itemName)	ViewerApiExtension.canPerformDrillDown(itemName)
ASPxClientDashboard.CanPerformDrillUp(itemName)	ViewerApiExtension.canPerformDrillUp(itemName)
ASPxClientDashboard.ItemDrillDownStateChanged	ViewerApiExtensionOptions.onItemDrillDownStateChanged

How to drill down on the client:

• ASP.NET MVC
• ASP.NET Web Forms

Selection

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.GetCurrentSelection(itemName)	ViewerApiExtension.getCurrentSelection(itemName)
ASPxClientDashboard.ItemSelectionChanged	ViewerApiExtensionOptions.onItemSelectionChanged
ASPxClientDashboard.GetAvailablePredefinedRanges(itemName)	ViewerApiExtension.getAvailablePredefinedRanges(itemName)
ASPxClientDashboard.GetCurrentPredefinedRange(itemName)	ViewerApiExtension.getCurrentPredefinedRange(itemName)
ASPxClientDashboard.GetEntireRange(itemName)	ViewerApiExtension.getEntireRange(itemName)
ASPxClientDashboard.SetPredefinedRange(itemName, dateTimePeriodName)	ViewerApiExtension.setPredefinedRange(itemName, dateTimePeriodName)

How to add custom interactivity to a dashboard:

• ASP.NET Core

Customization

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.ItemWidgetCreated	ViewerApiExtensionOptions.onItemWidgetCreated
ASPxClientDashboard.ItemWidgetUpdated	ViewerApiExtensionOptions.onItemWidgetUpdated
ASPxClientDashboard.ItemWidgetUpdating	ViewerApiExtensionOptions.onItemWidgetUpdating
ASPxClientDashboard.DashboardBeginUpdate	DashboardControlOptions.onDashboardBeginUpdate
ASPxClientDashboard.DashboardEndUpdate	DashboardControlOptions.onDashboardEndUpdate
ASPxClientDashboard.DashboardInitialized	DashboardControlOptions.onDashboardInitialized
ASPxClientDashboard.DashboardInitializing	DashboardControlOptions.onDashboardInitializing
ASPxClientDashboard.ItemBeginUpdate	DashboardControlOptions.onItemBeginUpdate
ASPxClientDashboard.ItemEndUpdate	DashboardControlOptions.onItemEndUpdate
ASPxClientDashboard.CustomizeDataSourceWizard	DataSourceWizardExtensionOptions.onCustomizeDataSourceWizard
ASPxClientDashboard.ItemElementCustomColor	ViewerApiExtensionOptions.onItemElementCustomColor

How to create a JSON connection at runtime:

• ASP.NET Core

How to calculate the Viewer’s layout size based on the dashboard size:

• ASP.NET Core

Dashboard State

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.GetDashboardState	DashboardControl.getDashboardState
ASPxClientDashboard.SetDashboardState(dashboardState)	DashboardControl.setDashboardState(dashboardState)
ASPxClientDashboard.DashboardStateChanged	DashboardControlOptions.onDashboardStateChanged

How to save a dashboard state to cookies:

• ASP.NET Core
• ASP.NET MVC

How to store dashboard state in the dashboard layout:

• ASP.NET MVC

Work with Data

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.Refresh	DashboardControl.refresh
ASPxClientDashboard.ReloadData	DashboardControl.reloadData
ASPxClientDashboard.RequestUnderlyingData(itemName, args, onCompleted)	ViewerApiExtension.requestUnderlyingData
ASPxClientDashboard.GetItemData(itemName)	ViewerApiExtension.getItemData(itemName)

How to obtain underlying data for the specified dashboard item:

• ASP.NET Core
• ASP.NET MVC
• ASP.NET Web Forms

How to reset the data source cache:

• ASP.NET Core
• ASP.NET MVC
• ASP.NET Web Forms

Toolbar Customization

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.DashboardTitleToolbarUpdated	ViewerApiExtensionOptions.onDashboardTitleToolbarUpdated
ASPxClientDashboard.ItemCaptionToolbarUpdated	ViewerApiExtensionOptions.onItemCaptionToolbarUpdated
ASPxClientDashboard.UpdateDashboardTitleToolbar	ViewerApiExtension.updateDashboardTitleToolbar
ASPxClientDashboard.UpdateItemCaptionToolbar(itemName)	ViewerApiExtension.updateItemCaptionToolbar

How to add custom properties:

• ASP.NET Core
• ASP.NET MVC
• ASP.NET Web Forms
• Angular

JavaScript Customization for Dashboard components for Blazor:

• Blazor WebAssembly
• Blazor Server

How to export all dashboard items into the same PDF document:

• ASP.NET Core

Export Data

Common

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.ShowExportDashboardDialog(format)	DashboardExportExtension.showExportDashboardDialog(format)
ASPxClientDashboard.ShowExportDashboardItemDialog(itemComponentName, format)	DashboardExportExtension.showExportDashboardItemDialog(itemComponentName, format)
ASPxClientDashboard.HideExportDialog	DashboardExportExtension.hideExportDialog

To PDF

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.ExportDashboardItemToPdf(itemName)	DashboardExportExtension.exportDashboardItemToPdf(itemName)
ASPxClientDashboard.ExportToPdf	DashboardExportExtension.exportToPdf
ASPxClientDashboard.SetPdfExportOptions(options)	DashboardExportExtension.setPdfExportOptions(options)
ASPxClientDashboard.GetPdfExportOptions	DashboardExportExtension.getPdfExportOptions

To Excel

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.ExportDashboardItemToExcel(itemName)	DashboardExportExtension.exportDashboardItemToExcel(itemName)
ASPxClientDashboard.ExportToExcel	DashboardExportExtension.exportToExcel
ASPxClientDashboard.SetExcelExportOptions(options)	DashboardExportExtension.setExcelExportOptions(options)
ASPxClientDashboard.GetExcelExportOptions	DashboardExportExtension.getExcelExportOptions

To Image

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.ExportDashboardItemToImage(itemName)	DashboardExportExtension.exportDashboardItemToImage(itemName)
ASPxClientDashboard.ExportToImage	DashboardExportExtension.exportToImage
ASPxClientDashboard.SetImageExportOptions(options)	DashboardExportExtension.setImageExportOptions(options)
ASPxClientDashboard.GetImageExportOptions	DashboardExportExtension.getImageExportOptions

Parameters

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.DynamicLookUpValuesLoaded	DashboardParameterDialogExtensionOptions.onDynamicLookUpValuesLoaded
ASPxClientDashboard.GetParameters	DashboardParameterDialogExtension.getParameters
ASPxClientDashboard.HideParametersDialog	DashboardParameterDialogExtension.hide
ASPxClientDashboard.ShowParametersDialog	DashboardParameterDialogExtension.show

How to specify dashboard parameter values on the client:

• ASP.NET Web Forms

Designer and Viewer Modes

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.SwitchToDesigner	DashboardControl.switchToDesigner DashboardPanelExtension.switchToDesigner
ASPxClientDashboard.SwitchToViewer	DashboardPanelExtension.switchToViewer DashboardControl.switchToViewer
ASPxClientDashboard.IsDesignMode	DashboardControl.isDesignMode
ASPxClientDashboard.GetWorkingMode	DashboardControlOptions.workingMode

How to switch between Designer and Viewer modes:

• ASP.NET MVC
• ASP.NET Web Forms

Work with a Dashboard

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.GetDashboardId	DashboardControl.getDashboardId
ASPxClientDashboard.LoadDashboard(dashboardId)	OpenDashboardExtension.loadDashboard(dashboardId) DashboardControl.loadDashboard(dashboardId)
ASPxClientDashboard.SaveDashboard	SaveDashboardExtension.saveDashboard SaveDashboardExtension.performSaveDashboard(dashboardId, dashboardJson)

Maximize and Restore Items

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.MaximizeDashboardItem(itemName)	DashboardControl.maximizeDashboardItem(itemName)
ASPxClientDashboard.GetMaximizedDashboardItemName	DashboardControl.maximizedDashboardItemName
ASPxClientDashboard.RestoreDashboardItem	DashboardControl.restoreDashboardItem

Data Inspector

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.ShowDataInspector(itemName, inspectedType)	DataInspectorExtension.showDataInspector(dashboardItemName)
ASPxClientDashboard.HideDataInspector	DataInspectorExtension.hideDataInspector

Tab Pages

ASPxClientDashboard API	DashboardControl API
ASPxClientDashboard.GetSelectedTabPage(tabContainerName)	ViewerApiExtension.getSelectedTabPage(tabContainerName)
ASPxClientDashboard.GetSelectedTabPageIndex(tabContainerName)	ViewerApiExtension.getSelectedTabPageIndex(tabContainerName)
ASPxClientDashboard.SetSelectedTabPage(tabPageName)	ViewerApiExtension.setSelectedTabPage(tabPageName)
ASPxClientDashboard.SetSelectedTabPageIndex(tabContainerName, index)	ViewerApiExtension.setSelectedTabPageIndex(tabContainerName,index)
ASPxClientDashboard.SelectedTabPageChanged	ViewerApiExtensionOptions.onSelectedTabPageChanged

How to change chart arguments at runtime:

• ASP.NET Core