Standalone Report Parameters Panel in React Applications

• May 02, 2024
• 5 minutes to read

The Standalone Report Parameters Panel is a component that creates a layout with editors for report parameters. It retrieves information on report parameters from a DevExpress report instance passed from the backend.

Use this component to programmatically create a report, then export or email it without showing a preview to the end user. The component reduces memory usage because it eliminates the need to generate report images in the background and send them to the client application.

The Standalone Report Parameters Panel component is based on the Parameters Panel of the DevExpress Web Report Viewer component. Public properties and events are similar to the properties and events implemented in the Web Document Viewer component.

Add a Standalone Report Parameters Panel to Your Application

The application is based on a backend server project and includes a React client part.

Backend Part (ASP.NET Core)

For information on how to create a backend part, review the corresponding section in the ASP.NET Core tutorial: Configure the Server Part (Backend).

Client Part (React Application)

1. Start with a React application. You can create a new React app from a template:

   npx create-react-app react-parameters-panel
   

2. Change your current directory to the project root folder and install the following packages:

   • devextreme
   • @devexpress/analytics-core
   • devexpress-reporting

   cd react-parameters-panel
   npm install devextreme@24.1-stable @devexpress/analytics-core@24.1-stable devexpress-reporting@24.1-stable
   

   Note

   Front-end and back-end applications should use the same version of DevExpress controls.

3. Create the Standalone Report Parameters Panel component:

   App.js

   import './App.css';
   import { useEffect, useRef } from 'react';
   import { DxReportParametersPanel } from 'devexpress-reporting/dx-webdocumentviewer';
   import * as ko from 'knockout';
   import $ from 'jquery';
   
   const ParametersPanel = () => {
   const reportUrl = ko.observable("TestReport");
   const viewerRef = useRef();
   const requestOptions = {
       host: "https://localhost:5001/",
       invokeAction: "DXXRDV"
   };
   useEffect(() => {
       const viewer = new DxReportParametersPanel(viewerRef.current, 
       { reportUrl, 
           requestOptions,
           callbacks: {
           BeforeRender: function(s, e) {
               const panel = s.GetParametersModel();
               panel.buttons.push({
                   onClick: () => {
                       const data = s.SerializeParametersState();
                       $.ajax({
                           url: "ExportWithParameters",
                           method: 'POST',
                           data: { serializedParameters: data, reportUrl: "TestReport" }
                       }).then(result => {
                           alert(result.message);
                       });
                   },
                   text: 'Send'
               });
               panel.showButtons = true;
           }
           }
           });
       viewer.render(); 
       return () => viewer.dispose();
   })
   return (<div ref={viewerRef}></div>);
   }
   
   function App() {
   return (<div style={{ width: "100%", height: "1000px" }}>
       <ParametersPanel />
   </div>);
   }
   
   export default App;
   

   App.css

   /* ... */
   /* Append the following lines: */
   @import url("../node_modules/devextreme/dist/css/dx.light.css");
   @import url("../node_modules/@devexpress/analytics-core/dist/css/dx-analytics.common.css");
   @import url("../node_modules/@devexpress/analytics-core/dist/css/dx-analytics.light.css");
   @import url("../node_modules/devexpress-reporting/dist/css/dx-webdocumentviewer.css");
   

In this example, a Send button is added to the Standalone Report Parameters Panel. When a user clicks this button, parameter values are sent to the server for processing by the controller action.

Implement the Controller Action

The client’s parameter data is sent to the ExportWithParameters controller action. In this action code, call the ApplyParametersStateAsync method to apply parameters to the report.

Once the report instance has all the necessary parameter values, it is ready to generate a document. Call the ExportToPdf method to create a PDF document from the report.

HomeController.cs

using DevExpress.XtraReports.Web.ParametersPanel;
using Microsoft.AspNetCore.Mvc;
// ...
    public async Task<IActionResult> ExportWithParameters(
    [FromServices] IReportParametersSerializer reportParametersSerializer,
    [FromServices] IWebHostEnvironment env,
    [FromForm] string serializedParameters,
    [FromForm] string reportUrl) {
        var report = await reportParametersSerializer.(reportUrl,
            serializedParameters);
        report.ExportToPdf(Path.Combine(env.ContentRootPath,
            "Reports", $"{reportUrl}.pdf"));
        return Ok(new { message = "Report exported successfully" });
    }

The PDF file is saved to the Reports folder in the project.

Standalone Report Parameters Panel Component Settings

The following component settings are critical for component integration:

reportUrl

A string that identifies a report. This string is passed to server-side report name resolution services. You can create a ReportStorageWebExtension or IReportProvider descendant, and register it in your back-end application as a custom report name resolution service. For more information, review the following help topic: Open a Report in ASP.NET Core Application.

invokeAction

Specifies a route to the controller that handles requests in your back-end application. A controller with the DXXRDV route is an internal MVC controller that is added to the back-end application when the methods AddDevExpressControls and UseDevExpressControls are called in the Startup.cs file. You can implement a WebDocumentViewerController descendant and register it as a controller with a custom route. To see a code sample, review the following help topic: ASP.NET Core and Angular Reporting Best Practices.

host

The back-end application’s URL.

Standalone Report Parameters Panel API

Client-Side API

The following types and members implement client-side Standalone Report Parameters Panel functionality:

JSReportParametersPanel

A class that triggers events for the Standalone Report Parameters Panel and serves as the sender in callback functions.

JSReportParametersPanel.GetParametersModel

Allows you to access the report parameters client-side model.

JSReportParametersPanel.SerializeParametersState

Serializes parameter information from the Standalone Report Parameters Panel to a JSON string.

ParametersPanelModelBase

A base class that defines common properties and methods for client models of report parameters.

ParametersPanelStandalone

Client-side model for the Standalone Report Parameters Panel component.

Server API

The component events (callbacks) are defined using ReportParametersPanelClientSideEventsBuilder methods:

• BeforeRender(String)
• CustomizeLocalization(String)
• CustomizeParameterEditors(String)
• CustomizeParameterLookUpSource(String)
• OnInitializing(String)
• OnServerError(String)
• ParametersInitialized(String)
• ParametersReset(String)

Classes related to the server-side model:

IReportParametersPanelClientSideModelGenerator

A class used to generate a client-side model for the Standalone Report Parameters Panel component.

ReportParametersPanelModel

A class that is the server-side model for the Standalone Report Parameters Panel.

This service allows you to pass a string obtained from the client’s SerializeParametersState method. The return object is a report instance with the applied parameters:

IReportParametersSerializer

Defines methods that enable you to deserialize parameters received from the Standalone Report Parameters Panel component and apply parameters to a report instance.

Panel Builder

ParameterPanelFluentBuilder

Contains methods that allow you to customize the Parameters panel.