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 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 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 Knockout bindings. For more information on Knockout bindings, review the following help topic: Document Viewer Client-Side Configuration (Knockout Bindings)
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 React 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. |