ReportViewer JavaScript API

JavaScript API

One of the new features we added to the ASP.Net Report Viewer in Visual Studio 2010 is a JavaScript API to allow you to interact with the viewer on client.  In reading many of the posts on the report controls forum, we found that many people struggle when implementing a custom toolbar or replacing portions of the toolbar functionality.  The new JavaScript API is intended to make it easier for you to provide the same functionality available through the built-in toolbar with a minimum amount of effort.

The JavaScript API is exposed through the client side ReportViewer object.  Specifically, it’s the Microsoft.Reporting.WebFormsClient.ReportViewer class.  An instance of this class is created on the client for each instance of the ReportViewer control on the page.

Referencing the client side viewer

The ReportViewer client side object inherits from Sys.UI.Control.  To obtain a reference to the client side viewer, use the $find method as follows:

    var clientViewer = $find("ReportViewer1");

The identifier you pass to $find corresponds to the ClientID of the ReportViewer server control.

Checking the state of the viewer

Once you have a reference to the client side viewer, you will want to check the state of the viewer before invoking most of the various methods and properties it exposes.  When the viewer is in a loading state, most of the functionality of the client viewer is unavailable and will throw an exception if called.  The viewer is loading whenever an asynchronous postback is in progress.  It is also in the loading state while retrieving a report page.  This usually happens during an asynchronous postback, but can also extend beyond the lifetime of the postback, such as while retrieving images displayed on the report page.  To check the state of the viewer, use the isLoading property:

    var isLoading = clientViewer.get_isLoading();

Once you have determined that the viewer is no longer loading new data, you can determine what is being displayed using the reportAreaContentType property.  It will indicate if the viewer is blank, displaying a report, or displaying an error message:

    if (!isLoading)
    {
        var reportAreaContentType = clientViewer.get_reportAreaContentType();
        if (reportAreaContentType ===
            Microsoft.Reporting.WebFormsClient.ReportAreaContent.ReportPage)
        {    
            // Perform various operations
        }
    }

Both the isLoading and the reportAreaContentType properties as well as all of the other properties on the client viewer fire the propertyChanged event.  Listening to that event can be useful for determining when you should enable or disable your custom UI.

Client side operations

The client side report viewer supports a number of operations, similar to those available with the built-in toolbar.  MSDN has a list of public properties and methods available on the client side report viewer.  It includes everything from invoking the print control and exporting a report to setting the zoom and scroll position of the report.  The built-in toolbar uses the public JavaScript API to perform its operations, so invoking the exportReport method on the client viewer will look exactly the same as selecting an export format from the built-in dropdown.

I have also included a sample with the article which demonstrates some of the new JavaScript APIs.  The sample was written with Visual Studio 2010 Beta 2.

Published Monday, November 09, 2009 2:00 PM by Brian Hartman

Filed under: ReportViewer, WebForms

Attachment(s): ReportViewerJavaScriptSample.zip

Microsoft.Reporting.WebFormsClient.ReportViewer Class

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Provides properties, methods, and events for client-side programming of the ReportViewer control.

An instance of this class is created by the ReportViewer control. To access the handle to this instance, use the Sys.Application $find Method.

var v = $find(viewerId);

  Members

Name
Description

Microsoft.Reporting.WebFormsClient.ReportViewer.ReportAreaContent Enumeration

Specifies the current state of the report area.

Microsoft.Reporting.WebFormsClient.ReportViewer.reportAreaChanged Event

Occurs when the report area is changed.

Microsoft.Reporting.WebFormsClient.ReportViewer.exportReport Method

Exports the report to the specified format.

Microsoft.Reporting.WebFormsClient.ReportViewer.find Method

Causes the server control to search for a string in the report.

Microsoft.Reporting.WebFormsClient.ReportViewer.findNext Method

Finds the next search hit in the report.

Microsoft.Reporting.WebFormsClient.ReportViewer.invokePrintDialog Method

Launches the print dialog.

Microsoft.Reporting.WebFormsClient.ReportViewer.refreshReport Method

Refreshes the report.

Microsoft.Reporting.WebFormsClient.ReportViewer.documentMapVisibility Property

Gets or sets a Boolean value that indicates whether the document map is visible.

Microsoft.Reporting.WebFormsClient.ReportViewer.isLoading Property

Gets a Boolean value that indicates whether the server control is loading a report.

Microsoft.Reporting.WebFormsClient.ReportViewer.promptAreaCollapsed Property

Gets or sets a Boolean value that indicates whether the parameter prompt area is visible.

Microsoft.Reporting.WebFormsClient.ReportViewer.reportAreaContent Property

Gets the current report area state.

Microsoft.Reporting.WebFormsClient.ReportViewer.zoomLevel Property

Gets or sets the current zoom level.

  Remarks

Depending on the state of the ReportViewer server control, accessing the methods and properties of the client side API may cause an exception. For example, When the Web page or the ReportViewer server control is performing a postback, accessing any of the methods or properties will cause an exception with the message: "The report or page is being updated. Please wait for the current action to complete."

When the Web page or the ReportViewer server control is not performing a postback, a set of methods require that a report is loaded. If no report is loaded, invoking those methods will cause an exception with the message: "The operation cannot be performed because there is no report loaded." See below for the applicable methods.

• Microsoft.Reporting.WebFormsClient.ReportViewer.invokePrintDialog Method

• Microsoft.Reporting.WebFormsClient.ReportViewer.exportReport Method

• Microsoft.Reporting.WebFormsClient.ReportViewer.find Method

• Microsoft.Reporting.WebFormsClient.ReportViewer.findNext Method

  Handling Property Change Events

If you want to be notified when a property is changed, register an event handler with the Sys.Component.propertyChanged Event. This event is part of the ReportViewer instance's base class, the Sys.Component Class. For example:

Copy Code

<script language="JavaScript">
   function propertyChangedHandler(sender, e)
   {
      alert("prop changed");
   }

   var rViewer = $find(viewerId);
   rViewer.add_propertyChanged(propertyChangedHandler);</script>

http://blogs.msdn.com/brianhartman/archive/2009/11/09/javascript-api.aspx

http://msdn.microsoft.com/en-us/library/dd756405(VS.100).aspx