The requested page is not available for the requested platform. You are viewing the content for Default platform.

Report Designer's Client-Side API

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.

The DevExpress.XtraReports.Web.Scripts namespace contains classes that implement the client-side functionality of the Report Designer.

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.
Print 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.
See Also