How to: Add a Dashboard Extension to an XAF ASP.NET Core Blazor Application
- 2 minutes to read
You can use extensions to customize the dashboard control used by the Dashboards Module. This topic integrates a simple example extension into your XAF ASP.NET Core Blazor application.
#Step-by-Step Instructions
Copy the following dashboard extension files to the YourApplicationName.Blazor.Server\wwwroot folder:
BlazorDashboardApp\wwwroot\parameter-item.js. This file contains the definition of the
ParameterCustomItem
extension. You will create a Controller that loads this script in the last step.javascriptwindow.ParameterCustomItem = /*...*/;
BlazorDashboardApp\wwwroot\dashboard-events-scripts.js. This file contains the code that registers the extension in the dashboard control and adds custom toolbar buttons to Grid item captions:
javascriptwindow.dashboardEvents = { onBeforeRender: (args) => { // Registers the Parameter item and the Dashboard Panel. var dashboardControl = args.component; dashboardControl.registerExtension(new ParameterCustomItem(dashboardControl)); // ... }, // Adds a new custom toolbar item to the dashboard item caption. extensions: { viewerApi: { onItemCaptionToolbarUpdated: function (e) { // ... } } } }
Create a new JavaScript file in the YourApplicationName.Blazor.Server\wwwroot folder and name it xaf-dashboard-user-script.js. Copy the following code snippet to the file:
javascriptconst xafDashboardUserScript = { onBeforeRender: function (dashboardControl) { window.dashboardEvents.onBeforeRender({ component: dashboardControl }); const viewerApi = dashboardControl.findExtension("viewerApi"); viewerApi.on("itemCaptionToolbarUpdated", window.dashboardEvents.extensions.viewerApi.onItemCaptionToolbarUpdated); } }; window.xafBlazorDashboardUserScripts = [xafDashboardUserScript];
xafDashboardUserScript
is a plain JavaScript object that contains a singleonBeforeRender
method. XAF calls this method before it renders a dashboard, becausexafDashboardUserScript
is included in thexafBlazorDashboardUserScripts
array. TheonBeforeRender
method does the following:- Calls the
window.dashboardEvents.onBeforeRender
method (defined in the dashboard-events-scripts.js file) that registers a custom toolbar item. - Ensures that the
onItemCaptionToolbarUpdated
method is called. XAF does not supportextensions: { viewerApi: { ... } }
syntax, therefore you must subscribe to theViewerApiExtension
‘s itemCaptionToolbarUpdated event explicitly.
- Calls the
To add custom scripts and the extension’s icons to the application, navigate to the YourApplicationName.Blazor.Server\Pages\_Host.cshtml file and add the following links to it: dashboard-events-scripts.js and xaf-dashboard-user-script.js.
html<link href="_content/DevExpress.ExpressApp.Blazor/styles.css" asp-append-version="true" rel="stylesheet" /> <link href="css/site.css" rel="stylesheet" /> <script src="dashboard-events-scripts.js"></script> <script src="xaf-dashboard-user-script.js"></script>
Navigate to YourApplicationName.Blazor.Server\App.razor and add the following line at the top of the file:
razor@DxResourceManager.RegisterScripts((config) => config.Register(new DxResource("/parameter-item.js", 900)))
This ensures that the parameter-item.js script is loaded in the correct order (after all other required scripts have been loaded).
The Parameter custom item is now available in the Dashboard Designer, and you can see a custom toolbar item in the first Grid dashboard item.