Report Designer's Client-Side API
- 8 minutes to read
The ReportDesignerExtension provides an advanced client-side API in addition to a comprehensive server-side object model.
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.
The DevExpress.XtraReports.Web.Scripts namespace contains classes that implement the web reporting controls’ client-side functionality.
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.
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. ReportStorageSetData Stores the specified report to a report storage using the specified URL. ReportStorageSetNewData Stores the specified report to a report storage using a new URL. The events below enable you to respond to opening and saving reports as well as 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
You can get and close the report tabs using the following methods:
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 changing and closing report tabs.
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 on adding them to a report:
Event Description CustomizeToolbox Enables you to customize the Web Report Designer’s available controls. 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 property 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 UI elements of the Report Designer and actions available in the Toolbar, Menu, and the Field List.
Event Description CustomizeElements Enables you to customize the Web Report Designer’s UI elements. CustomizeMenuActions Enables you to customize the Web Report Designer’s toolbar commands. CustomizeFieldListActions Enables you to customize actions available in the Web Report Designer’s Field List. Localize the Report Designer
Use the following API to substitute particular localization strings with custom ones 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
You can register custom parameter types in the End-User Report Designer as well as remove the available parameter types using the following methods:
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 both in 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
You can display the Report Designer’s preview using the following method:
Method Description ShowPreview Switches the Web Report Designer to the preview mode. The events listed below allow you to customize the built-in Document Viewer and respond to user actions made in preview.
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 Enumerators’ Values
In specific client-side events’ handlers, you can obtain the required elements by their IDs using the dedicated constants.
Use the following values to access the existing toolbar commands in the CustomizeMenuActions event:
DevExpress.Designer.ActionId
| Value | Description |
|---|---|
| Cut | The Cut toolbar button. |
| Copy | The Copy toolbar button. |
| Paste | The Paste toolbar button. |
| Delete | The Delete toolbar button. |
| Undo | The Undo toolbar button. |
| Redo | The Redo toolbar button. |
| ZoomOut | The Zoom Out toolbar button. |
| ZoomSelector | The drop-down list with available zoom factors. |
| ZoomIn | The Zoom In toolbar button. |
DevExpress.Designer.Report.ActionId
| Value | Description |
|---|---|
| NewReport | The New menu command. |
| NewReportViaWizard | The New via Wizard menu command. |
| OpenReport | The Open menu command. |
| ReportWizard | The Design in Report Wizard menu command. |
| Preview | The Preview toolbar button. |
| Scripts | The Scripts toolbar button. |
| AddDataSource | The drop-down list with available data sources in the Field List. |
| AddSqlDataSource | The Add SQL Data Source menu command that runs the Data Source Wizard single-query version. |
| AddMultiQuerySqlDataSource | The Add SQL Data Source menu command that runs the Data Source Wizard multi-query version. |
| Save | The Save menu command. |
| SaveAs | The Save As menu command. |
| Exit | The Exit menu command. |
| ValidateBindings | The Validate Bindings menu command. |
The following DevExpress.Report.Preview.ActionId values allows 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.Designer.Report.ReportDesignerElements object providing the following values:
| Value | Description |
|---|---|
| MenuButton | The menu button in the upper-left corner of the Designer’s user interfaces. |
| NavigationPanel | The panel at the bottom of the Designer displaying opened report tabs. |
| RightPanel | The panel at the right of the Designer and containing tabs with the Field List, Report Explorer and Properties Panel. |
| Surface | The design surface. |
| Toolbar | The Report Designer Toolbar. |
| Toolbox | The Toolbox containing report controls. |
In the PreviewCustomizeElements event handler, use the DevExpress.Report.Preview.PreviewElements object’s values listed below:
| Value | Description |
|---|---|
| RightPanel | The panel at the right of the Viewer and containing tabs with the Document Map, Parameters and Export Options. |
| Surface | The Viewer’s central part displaying the report document. |
| Toolbar | The Document Viewer’s Toolbar. |