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.