Document Viewer's Client-Side API

• Aug 01, 2019
• 5 minutes to read

The ASPxWebDocumentViewer control (WebDocumentViewerExtension in ASP.NET MVC) provides an advanced client-side API in addition to the comprehensive server-side object model. This enables web applications based on this control to function more efficiently using a combination of server-side and client-side processing.

Note

Although the entire client API is available on the client side, we recommend that you only use the documented public client-side API for any custom client functionality. The undocumented API can be changed or removed without any notifications, and applications using this API can stop working correctly after upgrading to a newer reporting controls version.

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, and the Client-Side Events topic to learn how to handle client-side events.

The client-side API of the Web Document Viewer allows you to perform the following actions:

• Open and Close Reports

  Use the following methods to open and close reports in the Document Viewer:

  Method	Description
  ASPxClientWebDocumentViewer.OpenReport	Opens the specified report on the Web Document Viewer’s client side.
  ASPxClientWebDocumentViewer.Close	Closes the document which is currently opened in the Web Document Viewer.

• Print and Export Reports

  The methods below allow you to print an entire report or its current page and export it to one of the supported third-party formats.

  Method	Description
  ASPxClientWebDocumentViewer.Print	Prints the current document or the document page with the specified index.
  ASPxClientWebDocumentViewer.ExportTo	Exports the current document to the specified file format.

• Build Documents

  The following API allows you to build report documents and respond to loading documents to the Document Viewer:

  Method	Description
  ASPxClientWebDocumentViewer.StartBuild	Starts building a report document.
  Event	Description
  ASPxClientWebDocumentViewer.DocumentReady	Occurs after the Web Document Viewer loads a report document.

• Navigate Through a Report

  You can navigate through a report using the following methods:

  Method	Description
  ASPxClientWebDocumentViewer.GoToPage	Displays the specified report page.
  ASPxClientWebDocumentViewer.GetCurrentPageIndex	Returns the current page’s zero-based index.

• Manage Interactivity

  The events below allow you to respond to clicking a report area and changing editing field values:

  Event	Description
  ASPxClientWebDocumentViewer.PreviewClick	Occurs when the left mouse button is clicked on a report document.
  ASPxClientWebDocumentViewer.EditingFieldChanged	Occurs each time an editing field’s value changes.

  Use the following method to provide a drill-through functionality to a report:

  Method	Description
  ASPxClientWebDocumentViewer.DrillThrough	Enables navigation between drill-through reports on the client-side.

• Customize Parameter Editors

  The following events allow you to provide custom editors for report parameters and/or customize look-up parameter values:

  Event	Description
  ASPxClientWebDocumentViewer.CustomizeParameterEditors	Occurs each time a standard editor is created for a report parameter based on a parameter type.
  ASPxClientWebDocumentViewer.CustomizeParameterLookUpSource	Occurs each time a look-up editor is created for a report parameter.

• Respond to Resetting and Submitting Parameters

  The API listed below allows you to reset and change parameter values.

  Event	Description
  ASPxClientWebDocumentViewer.ParametersReset	Occurs after report parameter values are reset to their default values.
  ASPxClientWebDocumentViewer.ParametersSubmitted	Occurs after report parameter values are submitted.
  Method	Description
  ASPxClientWebDocumentViewer.ResetParameters	Resets the report parameter values to the default values.

• Customize Document Viewer Elements and Actions

  The events below allow you to customize UI elements and toolbar actions:

  Event	Description
  ASPxClientWebDocumentViewer.CustomizeElements	Allows you to customize the Web Document Viewer’s UI elements.
  ASPxClientWebDocumentViewer.CustomizeMenuActions	Enables you to customize the Web Document Viewer’s menu actions.

• Localize the Document Viewer

  Use the following API to substitute specific localization strings with custom ones programmatically:

  Event	Description
  ASPxClientWebDocumentViewer.CustomizeLocalization	Enables you to customize the Web Document Viewer’s localization strings.
  Method	Description
  ASPxClientWebDocumentViewer.UpdateLocalization	Updates the Web Document Viewer properties’ localization settings.

• Initialize the Document Viewer

  Handle the following event to perform the required actions before the Web Document Viewer’s UI initialization:

  Event	Description
  ASPxClientWebDocumentViewer.BeforeRender	Occurs before the Web Document Viewer UI is initialized.

• Obtain Client-Side Models and Report Preview

  The following methods allow you to obtain client-side models of the Document Viewer and report parameters as well as actual report preview:

  Method	Description
  ASPxClientWebDocumentViewer.GetPreviewModel	Provides access to the Document Viewer’s client-side model.
  ASPxClientWebDocumentViewer.GetParametersModel	Provide access to the report parameters’ client-side model.
  ASPxClientWebDocumentViewer.GetReportPreview	Provides access to the report preview.

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 ASPxClientWebDocumentViewer.CustomizeMenuActions event:

Value	Description
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.
HightlightEditingFields	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 ASPxClientWebDocumentViewer.CustomizeElements 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.