Document Viewer Client-Side API
- 6 minutes to read
General Information
ASP.NET Web Forms
The ASPxClientWebDocumentViewer is the Document Viewer client-side object.
The ASPxDocumentViewer.ClientInstanceName property specifies a unique client-side identifier used to access the ASPxClientWebDocumentViewer object programmatically.
Use the Cient-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: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: How It Works.
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:
<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
The Document Viewer does not provide an identifier to access the client-side instance. Handle a Document Viewer client-side event and store the client instance (available using the sender variable) in a JavaScript variable.
Use the WebDocumentViewerBuilder.ClientSideEvents method to access an object that allows you to specify client-side event handlers.
<script type="text/javascript" id="script">
var docViewer;
function GetDocumentViewer(s, e) {
docViewer = s;
}
</script>
@(Html.DevExpress().WebDocumentViewer("WebDocumentViewer1")
.Height("1000px")
.ClientSideEvents(configure =>
{
configure.BeforeRender("GetDocumentViewer");
})
.Bind("Products"))
Angular
Use the DxReportViewerComponent component’s bindingSender property to access the client-side model:
import { Component, ViewEncapsulation, ViewChild } from '@angular/core';
import DevExpress from 'devexpress-reporting/dx-webdocumentviewer';
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.
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 Description OpenReport Opens the specified report on the Web Document Viewer’s client side. Allows you to refresh preview for the loaded report. 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 Description Print Prints the current document or the document page with the specified index. 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 Description StartBuild Starts building a report document. Navigate Through a Report
You can navigate through a report using the following methods:
Method Description GoToPage Displays the specified report page. GetCurrentPageIndex Returns the current page’s zero-based index. Manage Interactivity
The events fire when a user clicks a report area or changes editing 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 editing field’s value changes. Use the following method to provide a drill-through functionality to a report:
Method Description 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 (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description CustomizeParameterEditors CustomizeParameterEditors Occurs each time a standard editor is created for a report parameter based on a parameter type. 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 allows you to reset and change parameter values.
Event (ASP.NET Web Forms & MVC) Event (ASP.NET Core) Description ParametersReset ParametersReset Occurs after report parameter values are reset to their default values. ParametersSubmitted ParametersSubmitted Occurs after report parameter values are submitted. Method Description 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 customize the Web Document Viewer’s available export formats and corresponding 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 Description UpdateLocalization Updates the Web Document Viewer properties’ localization settings. 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 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 Description GetPreviewModel Provides access to the Document Viewer’s client-side model. GetParametersModel Provide access to the report parameters’ client-side model. GetReportPreview Provides access to the report preview. Perform a Custom Operation
Call the following method to perform a custom operation on the client-side:
Method Description PerformCustomDocumentOperation Performs a custom operation with a currently opened document on the client-side.