Document Viewer Client-Side API

• Mar 07, 2024
• 8 minutes to read

General Information

ASP.NET Web Forms

The ASPxClientWebDocumentViewer is the Document Viewer client-side object.

The ASPxWebDocumentViewer.ClientInstanceName property specifies a unique client-side identifier used to access the ASPxClientWebDocumentViewer object programmatically.

Use the Client-Side Event Editor or the ASPxWebDocumentViewer.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 prints a report:

ASP.NET Web Forms

<asp:Content ID="Content" ContentPlaceHolderID="MainContent" runat="server">
    <script type="text/javascript">
        function PrintOnClick(s, e) {
            WebDocumentViewer1.Print();
        }
</script>

<dx:ASPxButton ID="ASPxButton1" runat="server" Text="Print Document" AutoPostBack="False">
    <ClientSideEvents Click="PrintOnClick" />
</dx:ASPxButton>

<dx:ASPxWebDocumentViewer ClientInstanceName="WebDocumentViewer1" ID="ASPxWebDocumentViewer1" runat="server"  DisableHttpHandlerValidation="False">
</dx:ASPxWebDocumentViewer>
</asp:Content>

ASP.NET MVC

The DocumentViewerExtension accepts the specified settings, binds the Document Viewer to the specified report and renders the Document Viewer 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 WebDocumentViewerSettings.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 prints a report:

ASP.NET MVC

<script type="text/javascript">
    function PrintOnClick(s, e) {
        WebDocumentViewer1.Print();
    }
</script>

@Html.DevExpress().Button(settings =>
{
    settings.Name = "dxPrintButton";
    settings.Text = "Print Document";
    settings.ClientSideEvents.Click = "PrintOnClick";
}).GetHtml()

@Html.DevExpress().WebDocumentViewer(settings =>
{
    settings.Name = "WebDocumentViewer1";
}).Bind("Products").GetHtml()

ASP.NET Core

Use a string identifier assigned to the Name property to access the client-side Document Viewer. The client instance exposes the IPreviewModel interface, and you can use the IPreviewModel methods to accomplish your task.

Use the WebDocumentViewerBuilder.ClientSideEvents method to access an object that allows you to specify client-side event handlers.

The following code hides the Document Viewer’s TabPanel and creates a button that opens a report:

ASP.NET Core

<script type="text/javascript" id="script">
    function onClick() {
        DocViewer.OpenReport("TestReport");
    }
    function onCustomizeElements(s, e) {
        var panelPart = e.GetById(DevExpress.Reporting.Viewer.PreviewElements.RightPanel);
        var index = e.Elements.indexOf(panelPart);
        e.Elements.splice(index, 1);
    }
</script>    

<button onclick="onClick()" type="button">
    Open Report
</button>
@{
    var viewerRender = Html.DevExpress().WebDocumentViewer("DocViewer")
        .Height("1000px")
        .ClientSideEvents(configure =>
        {
            configure.CustomizeElements("onCustomizeElements");
        })
        .Bind("XtraReport1");
    @viewerRender.RenderHtml()
}

Angular

Use the DxReportViewerComponent component’s bindingSender property to access the client-side model:

---

app.component.ts

import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import { DxReportViewerComponent} from 'devexpress-reporting-angular'; 

@Component({
// ...
})
export class AppComponent {
  @ViewChild(DxReportViewerComponent) viewer: DxReportViewerComponent; 
  // ...

  print() {  
   this.viewer.bindingSender.Print(); 
  }  
}

Review the following help topic for a complete example: Document Viewer Client-Side Configuration in an Angular Application.

React

Use the JSReportViewer 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 WebDocumentViewerClientSideEventsBuilder 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 JSReportViewer 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: WebDocumentViewerClientSideEventsBuilder.

Client-Side API

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 (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
OpenReport	OpenReport	Opens the specified report on the Web Document Viewer’s client side. Allows you to refresh preview for the loaded report.
Close	Close	Closes the document that is currently open 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 a third-party format.

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
Print	Print	Prints the current document or the document page with the specified index.
ExportTo	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:

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
DocumentReady	DocumentReady	Occurs after the Web Document Viewer loads a report document.

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
StartBuild	StartBuild	Starts building a report document.

Navigate Through a Report

You can use the following methods to navigate through a report:

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
GoToPage	GoToPage	Displays the specified report page.
GetCurrentPageIndex	GetCurrentPageIndex	Returns the current page’s zero-based index.

Manage Interactivity

The following events fire when a user clicks a report area or changes edit field values:

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
PreviewClick	PreviewClick	Occurs when a report document is clicked.
EditingFieldChanged	EditingFieldChanged	Occurs each time an edit field’s value changes.

Use the following method to allow users to drill-through reports:

Method (ASP.NET Web Forms & MVC)	Description
DrillThrough	Enables navigation between drill-through reports on the client-side.

Customize Parameter Editors

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

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
CustomizeParameterEditors	CustomizeParameterEditors	Allows you to customize parameter editors in the Parameters panel.
CustomizeParameterLookUpSource	CustomizeParameterLookUpSource	Occurs each time a look-up editor is created for a report parameter.

Respond to Parameter Reset and Submit

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

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
ParametersReset	ParametersReset	Raised after report parameter values are reset to their default values.
ParametersSubmitted	ParametersSubmitted	Occurs after a user submits report parameter values.

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
ResetParameters	IPreviewModel.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, toolbar actions and export options:

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
CustomizeElements	CustomizeElements	Allows you to customize the Web Document Viewer’s UI elements.
CustomizeMenuActions	CustomizeMenuActions	Enables you to customize Web Document Viewer menu actions.
CustomizeExportOptions	CustomizeExportOptions	Allows you to hide export formats and specify the default export options.

Localize the Document Viewer

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

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
CustomizeLocalization	CustomizeLocalization	Enables you to customize the Web Document Viewer’s localization strings.

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
UpdateLocalization	UpdateLocalization	Substitutes the specified localizable strings with translations.

Respond to Server-Side Errors

Use the following event to perform the required actions when a server-side error occurs:

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
OnServerError	OnServerError	Raised when a server-side error occurs.

Initialize the Document Viewer

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

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
BeforeRender	BeforeRender	Occurs before the Web Document Viewer UI is initialized.

Obtain Client-Side Parameters, Models and Report Preview

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

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
GetPreviewModel	GetPreviewModel	Provides access to the Document Viewer’s client-side model.
GetReportPreview	GetReportPreview	Provides access to the report preview.
GetParametersModel	GetParametersModel	Allows you to obtain report parameters on the client.
ParametersInitialized	ParametersInitialized	Specifies the JavaScript function that handles the client-side ParametersInitialized event and allows you to get the client-side parameter values when they are initialized and modify them.

Initialize Parameters

Subscribe to the following events to be able to specify initial parameter values:

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
ParametersInitialized	ParametersInitialized	Specifies the JavaScript function that handles the client-side ParametersInitialized event and allows you to get the client-side parameter values when they are initialized and modify them.

Assign values to different types of parameters in the ParameterInitialized event, as follows

function onParametersInitialized(sender, e) {
    var p1 = e.ActualParametersInfo
        .filter(x => x.parameterDescriptor.name == "parameter1")[0];
    // Date Range parameter
    //p1.value = [new Date('04/01/2023'), new Date(`01/01/2024`)];
    // Multi-Value parameter
    //p1.value = [7,8,9,12];
    // Numeric parameter of type double
    p1.value = 1.2345;
    p1 && e.Submit();
}

Perform a Custom Operation

Call the following method to perform a custom operation on the client:

Method (ASP.NET Web Forms & MVC)	Method (ASP.NET Core)	Description
PerformCustomDocumentOperation	PerformCustomDocumentOperation	Sends data to the server to execute a custom operation on a currently opened document.

Implement Request Authentication

Handle the following events to implement token-based authentication:

Event (ASP.NET Web Forms & MVC)	Event (ASP.NET Core)	Description
OnExport	OnExport	Specifies the JavaScript function that handles the OnExport event, which occurs before a request for document export is sent.