Report Designer's Client-Side API
- 7 minutes to read
The ASPxReportDesigner control provides an advanced client-side API in addition to a comprehensive server-side object model. ASPxClientReportDesigner is a client-side equivalent of this control.
Note
Although the entire client API is available on the client side, we strongly recommend that you use only the documented public client-side API for any custom client functionality. The code with the undocumented API can stop working after an upgrade to a new version of reporting controls.
Refer to Client-Side Functionality Overview for more information on the DevExpress client-side model implementation. See the Client-Side Events topic to learn how to handle client-side events.
Note
To access the client-side model, use the bindingSender property as demonstrated below:
this.reportDesigner.bindingSender.SaveReport("reportName");
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 on the Web Report Designer’s client side. SaveReport Saves the current report. SaveNewReport Saves the current report under a new name. ReportStorageSetData Stores the specified report to a report storage using the specified URL. ReportStorageGetUrls Returns the report URLs and display names existing in a report storage. ReportStorageSetNewData Stores the specified report to a report storage using a new URL. Use the events below to respond to a report’s ‘open’ and ‘save’ operations. You can also customize dialogs used to open and save reports.
Event Description ReportOpening Occurs when a report is about to be opened in the Web Report Designer. ReportOpened Occurs when a report has been opened in the Web Report Designer. ReportSaving Occurs when a report is about to be saved in the Web Report Designer. ReportSaved Occurs when a report has been saved in the Web Report Designer. CustomizeOpenDialog Enables you to customize the Open Report dialog of the Web Report Designer. CustomizeSaveDialog Enables you to customize the Save dialog of the Web Report Designer. 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 Description TabChanged Occurs when an active report tab was changed in the Web Report Designer. ReportTabClosing Occurs when a report tab is about to be closed in the Web Report Designer. ReportTabClosed Occurs when a report tab was closed in the Web Report Designer. 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 Description CustomizeToolbox Enables you to customize the Toolbox of the Web Report Designer. 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 Returns information about the specified properties of the specified control. 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 Description CustomizeWizard Enables you to customize the Web Report Designer’s Report Wizard and Data Source Wizard. CustomizeElements Enables you to customize the Web Report Designer’s UI elements. CustomizeMenuActions Enables you to customize the Web Report Designer’s menu actions. 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 / Method Description CustomizeLocalization Enables you to customize the Web Report Designer’s localization strings. 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 Description CustomizeParameterEditors Occurs each time a standard editor is created for a report parameter based on a parameter type. 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 Description CallbackError Fires on the client if any server error occurs during server-side processing of a callback sent by ASPxClientReportDesigner. 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 Description 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 Description PreviewClick Occurs when the left mouse button is clicked on a report document in Print Preview. PreviewCustomizeElements Enables you to customize UI elements of a Document Viewer built into a Web Report Designer. PreviewCustomizeMenuActions Enables you to customize the actions of a Document Viewer built into a Web Report Designer. PreviewCustomizeExportOptions Allows you to customize available export formats and corresponding export options in a Document Viewer built into a Web Report Designer. PreviewDocumentReady Occurs after a report has been switched to Print Preview. PreviewEditingFieldChanged Occurs each time an editing field’s value changes in Print Preview. PreviewParametersReset Occurs after report parameter values are reset to their default values in Print Preview. PreviewParametersSubmitted 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 a client-side model of a Web Report Designer. GetPreviewModel Provides access to the Document Viewer’s client-side model.
Available Enumerator Values
In specific client-side event handlers, use element IDs and dedicated constants to obtain elements.
Use the following values to access existing toolbar commands in the CustomizeMenuActions event:
The following DevExpress.Reporting.Viewer.ActionId values allow you to access the Document Preview’s existing commands in the PreviewCustomizeMenuActions event:
| Value | Description |
|---|---|
| Design | The Designer toolbar button. |
| FirstPage | The First Page toolbar button. |
| PrevPage | The Previous Page toolbar button. |
| Pagination | The drop-down list that navigates to the selected page. |
| NextPage | The Next Page toolbar button. |
| LastPage | The Last Page toolbar button. |
| MultipageToggle | The Toggle Multipage Mode toolbar button. |
| HighlightEditingFields | The Highlight Editing Fields toolbar button. |
| ZoomOut | The Zoom Out toolbar button. |
| ZoomSelector | The drop-down list with available zoom factors. |
| ZoomIn | The Zoom In toolbar button. |
| The Print toolbar button. | |
| PrintPage | The Print Page toolbar button. |
| ExportTo | The Export To toolbar button. |
| Search | The Search toolbar button. |
In the CustomizeElements event handler, use the DevExpress.Reporting.Designer.Utils.ReportDesignerElements object, which provides the following values:
| Value | Description |
|---|---|
| MenuButton | The menu button in the upper-left corner of the Designer’s user interface. |
| NavigationPanel | The panel at the bottom of the Designer that displays opened report tabs. |
| RightPanel | The panel on the right side of the Designer that contains tabs with the Field List, Report Explorer and Properties Panel. |
| Surface | The design surface. |
| Toolbar | The Report Designer Toolbar. |
| Toolbox | The Toolbox that contains report controls. |
In the PreviewCustomizeElements event handler, use the DevExpress.Reporting.Viewer.PreviewElements object’s values listed below:
| Value | Description |
|---|---|
| RightPanel | The panel on the right side of the Viewer that contains tabs with the Document Map, Parameters and Export Options. |
| Surface | The Viewer’s central portion that displays the report document. |
| Toolbar | The Document Viewer’s Toolbar. |