Skip to main content
All docs
V24.2
.NET 8.0+

DevExpress v24.2 Update — Your Feedback Matters

Our What's New in v24.2 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

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

  1. 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.

      javascript
      window.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:

      javascript
      window.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) {
                      // ...
                  }
              }
          }    
      }
      
  2. 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:

    javascript
    const 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 single onBeforeRender method. XAF calls this method before it renders a dashboard, because xafDashboardUserScript is included in the xafBlazorDashboardUserScripts array. The onBeforeRender 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 support extensions: { viewerApi: { ... } } syntax, therefore you must subscribe to the ViewerApiExtension‘s itemCaptionToolbarUpdated event explicitly.
  3. 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>
    
  4. 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.

XAF ASP.NET Core Blazor Dashboard With Custom Extension, DevExpress