All docs
V21.1
21.1
20.2
20.1
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Report Designer Client-Side API

  • 8 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 the 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 the 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’s 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 DxReportViewerComponent 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 Angular Application.

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.
    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 the ‘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.
  • Get and Close Report Tabs

    Use the following methods to get 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 the 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 the Report Designer’s 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.
  • 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.