Skip to main content

Report Designer Client-Side API

  • 9 minutes to read

General Information

ASP.NET Web Forms

The ASPxClientReportDesigner is the Report Designer client-side object.

The ASPxReportDesigner.ClientInstanceName property specifies a unique client-side identifier used to access the ASPxClientReportDesigner object programmatically.

Use the Client-Side Event Editor or the ASPxReportDesigner.ClientSideEvents property to specify client-side event handlers.

The following code snippet illustrates how to use client-side API to create a button that opens a report in the Report Designer:

<asp:Content ID="Content" ContentPlaceHolderID="MainContent" runat="server">
    <script type="text/javascript">
        function OpenOnClick(s, e) {
            ReportDesigner1.OpenReport("TestReport");
        }
</script>

<dx:ASPxButton ID="ASPxButton1" runat="server" Text="Open Report" AutoPostBack="False">
    <ClientSideEvents Click="OpenOnClick" />
</dx:ASPxButton>

<dx:ASPxReportDesigner ClientInstanceName="ReportDesigner1" ID="ASPxReportDesigner1" runat="server"  DisableHttpHandlerValidation="False">
</dx:ASPxReportDesigner>
</asp:Content>

ASP.NET MVC

The ReportDesignerExtension accepts specified settings, binds the Report Designer to the specified report, and renders the Report Designer to the View.

Refer to the following help topic for more information on DevExpress ASP.NET MVC extensions: Get Started.

To access the client-side Document Viewer, assign a string identifier to the SettingsBase.Name property.

Use the ReportDesignerSettings.ClientSideEvents property to specify client-side event handlers.

The following code snippet illustrates how to use the client-side API to create a button that opens a report in the Report Designer:

<script type="text/javascript">
    function OpenOnClick(s, e) {
        ReportDesigner1.OpenReport("TestReport");
    }
</script>

@Html.DevExpress().Button(settings =>
{
    settings.Name = "dxOpenButton";
    settings.Text = "Open Report";
    settings.ClientSideEvents.Click = "OpenOnClick";
}).GetHtml()

@Html.DevExpress().ReportDesigner(settings =>
{
    settings.Name = "ReportDesigner1";
}).BindToUrl("TestReport").GetHtml()

ASP.NET Core

The Report Designer does not provide an identifier to access the client-side instance. Handle a Report Designer client-side event and store the client instance (available using the sender variable) in a JavaScript variable.

Use the ReportDesignerBuilder.ClientSideEvents method to access the ReportDesignerClientSideEventsBuilder object that allows you to specify client-side event handlers.

@(Html.DevExpress().ReportDesigner("ReportDesigner1")
    .Height("1000px")
    .ClientSideEvents(configure =>
        {
        configure.BeforeRender("GetReportDesigner");
    })
    .Bind("TestReport"))

Use the ReportDesignerClientSideEventsBuilder object’s Preview method to handle client-side events for the Report Designer’s integrated Document Viewer:

@(Html.DevExpress().ReportDesigner("reportDesigner1")
        .Height("1000px")
        .ClientSideEvents(configure => {
            configure.Preview(c => { c.CustomizeElements("previewCustomizeElements"); });
        })
        .Bind("TestReport"))

Angular

Use the DxReportDesignerComponent component’s bindingSender property to access the client-side model:

import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import { DxReportDesignerComponent} from 'devexpress-reporting-angular';

@Component({
    // ...
})

export class AppComponent {
  @ViewChild(DxReportDesignerComponent, { static: false }) designer: DxReportDesignerComponent;
  // ...

  open() {  
   this.designer.bindingSender.OpenReport("HelloWorld"); 
  } 

}

Review the following help topic for a complete example: Report Designer Client-Side Configuration in an Angular Application.

React

Use the JSReportDesigner class to access the client-side API in React applications.

Client-side events in React are handled with callbacks specified in the Callbacks component.

Event names and data in event arguments passed to the React callback handler functions are the same as events in an ASP.NET Core application specified with the ReportDesignerClientSideEventsBuilder methods.

Review the following help topic for more information: Reporting for React - Client-Side API

Vue

To access the client-side Reporting API in Vue applications, use the JSReportDesigner class.

Client-side events in Vue are handled with callbacks specified in the Knockout bindings.

Event names and data in event arguments passed to the Angular callback handler functions are the same as events in an ASP.NET Core application. Review the following help topic with information on ASP.NET Core client-side events: ReportDesignerClientSideEventsBuilder methods.

Review the following help topic for more information: Reporting for Vue - Client-Side API

Client-Side API

The Report Designer’s client-side API allows you to perform the following actions:

Open and Save Reports

Use the following methods to open and save reports in the Report Designer:

Method Description
OpenReport Opens the specified report.
IsModified Indicates whether a report loaded in the Report Designer is changed.
ResetIsModified Resets the value returned by the ASPxClientReportDesigner.IsModified method.
SaveReport Saves the current report.
SaveNewReport Saves the current report under a new name.
ReportStorageSetData Stores the report in a report storage and assigns the specified report identifier.
ReportStorageGetUrls Returns a list of report identifiers for the reports contained in the report storage.
ReportStorageSetNewData Stores the new report in a report storage and assigns the specified report identifier.

Use the following events to handle ‘open’ and ‘save’ operations. You can also customize dialogs used to open and save reports.

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
ReportOpening ReportOpening Occurs when a report is about to be opened in the Web Report Designer.
ReportOpened ReportOpened Occurs when a report has been opened in the Web Report Designer.
ReportSaving ReportSaving Occurs when a report is about to be saved in the Web Report Designer.
ReportSaved ReportSaved Occurs when a report has been saved in the Web Report Designer.
CustomizeOpenDialog CustomizeOpenDialog Enables you to customize the Open Report dialog of the Web Report Designer.
CustomizeSaveDialog CustomizeSaveDialog Enables you to customize the Save dialog of the Web Report Designer.
CustomizeSaveAsDialog CustomizeSaveAsDialog Enables you to customize the Save Report dialog of the Web Report Designer.

Retrieve and Close Report Tabs

Use the following methods to retrieve and close report tabs:

Method Description
GetCurrentTab Returns the currently active tab in the Web Report Designer.
GetTabs Returns all available Report Designer tabs.
CloseCurrentTab Closes the report tab currently being opened in the Web Report Designer.
CloseTab Closes the specified report tab in the Web Report Designer.

Use the following events to respond to a report tab’s ‘change’ and ‘close’ operations.

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
TabChanged TabChanged Occurs when an active report tab was changed in the Web Report Designer.
ReportTabClosing ReportTabClosing Occurs when a report tab is about to be closed in the Web Report Designer.
ReportTabClosed ReportTabClosed Occurs when a report tab was closed in the Web Report Designer.
ExitDesigner ExitDesigner Occurs on the client side when the Report Designer is being closed.

Customize Controls and Their Properties

The events below allow you to customize controls available in the Report Designer Toolbox and change their properties when they are added to a report:

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
CustomizeToolbox CustomizeToolbox } Enables you to customize the Toolbox of the Web Report Designer.
ComponentAdded ComponentAdded Occurs after a component has been added to the report currently being edited in the Web Report Designer.

Use the following methods to customize properties of existing controls and add new properties for custom controls:

Method Description
GetPropertyInfo Gets information displayed in the Properties Panel for the specified property of the specified control type.
AddToPropertyGrid Adds a custom property to the Properties Panel.

Customize Report Designer Elements and Actions

The events below allow you to customize Report Designer UI elements and actions available in the Toolbar, Menu, and Field List.

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
CustomizeWizard CustomizeWizard Enables you to customize the Web Report Designer’s Report Wizard and Data Source Wizard.
CustomizeElements CustomizeElements Enables you to customize the Web Report Designer’s UI elements.
CustomizeMenuActions CustomizeMenuActions Enables you to customize the Web Report Designer’s menu actions.
CustomizeFieldListActions CustomizeFieldListActions Enables you to customize actions available in the Web Report Designer’s Field List.

Localize the Report Designer

Use the following API to replace specific localization strings with custom strings programmatically:

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
CustomizeLocalization CustomizeLocalization Enables you to customize the Web Report Designer’s localization strings.
Method Description
UpdateLocalization Updates the Report Designer properties’ localization settings.

Manage Report Parameters

Use the following methods to register custom parameter types in the End-User Report Designer and remove available parameter types:

Method Description
AddParameterType Adds a custom parameter type to the Web End-User Report Designer.
RemoveParameterType Removes the specified parameter type from the Web End-User Report Designer.
GetParameterEditor Returns a value editor associated with the specified parameter type.
GetParameterInfo Returns an object that contains information on the specified parameter type.

The following events allow you to customize parameter editors in both design and preview modes:

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
CustomizeParameterEditors CustomizeParameterEditors Occurs each time a standard editor is created for a report parameter based on a parameter type.
CustomizeParameterLookUpSource CustomizeParameterLookUpSource Occurs each time a look-up editor is created for a report parameter.

Respond to Server-Side Errors

Use the following events to perform required actions when a server-side error occurs:

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
CallbackError Fires on the client if any server error occurs during server-side processing of a callback sent by ASPxClientReportDesigner.
OnServerError OnServerError Occurs on the client each time a server-side error raises.

Initialize the Report Designer

Handle the following event to perform the required actions before Report Designer UI initialization:

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
BeforeRender BeforeRender Occurs before the Web Report Designer UI is initialized.

Manage the Document Preview

Use the following method to display the Report Designer’s document preview:

Method Description
ShowPreview Switches the Web Report Designer to the preview mode.

The following events allow you to customize the built-in Document Viewer and respond to user actions performed in preview mode.

Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description
PreviewClick PreviewClick Occurs when the left mouse button is clicked on a report document in Print Preview.
PreviewCustomizeElements CustomizeElements Enables you to customize UI elements of a Document Viewer built into a Web Report Designer.
PreviewCustomizeMenuActions CustomizeMenuActions Enables you to customize the actions of a Document Viewer built into a Web Report Designer.
PreviewCustomizeExportOptions CustomizeExportOptions Allows you to customize available export formats and corresponding export options in a Document Viewer built into a Web Report Designer.
PreviewDocumentReady DocumentReady Occurs after a report has been switched to Print Preview.
PreviewEditingFieldChanged EditingFieldChanged Occurs each time an editing field’s value changes in Print Preview.
PreviewParametersReset ParametersReset Occurs after report parameter values are reset to their default values in Print Preview.
PreviewParametersSubmitted ParametersSubmitted Occurs after report parameter values are submitted in Print Preview.
PreviewOnExport OnExport Specifies the JavaScript function that handles the OnExport event, which occurs before a request for document export is sent.

Obtain Client-Side Models

The following methods allow you to obtain client-side models of the Report Designer and its built-in Document Viewer.

Method Description
GetDesignerModel Provides access to the client-side model of the Web Report Designer.
GetPreviewModel Provides access to the Document Viewer’s client-side model.