Crystal Reports XI Official Guide

An equivalent viewer to the Windows Forms Viewer exists for ASP.NET-based applications; it's called the Web Forms Viewer. This is an ASP.NET control derived from the WebControl class. This means that it is a server-side control that renders only HTML to the client browser. No special controls, applets, or files are required on the client in order to view reports with the Web Forms Viewer.

Like the Windows Forms Viewer, the Web Forms Viewer can be found in the Visual Studio .NET toolbox and is called CrystalReportViewer. It is found in the CrystalDecisions.Web namespace and the CrystalDecisions.Web.dll assembly. Many objects used in the Web Forms Viewer are contained in the CrystalDecisions.Shared namespace. The Web Forms Viewer has many properties and methods that control how it displays reports. This section covers these.

The first step to using the viewer is to drop it onto a Web Form from the toolbox. From there, properties can be set via the property browser or via the code-behind for the ASPX page. The first relevant property for the Web Forms Viewer is the ReportSource property. The nice thing is that the types of objects that can be passed into the ReportSource property are exactly the same as the types of objects that can be passed into the Windows Forms Viewer's ReportSource property. For more information on the ReportSource Property, refer to "The ReportSource Property" section earlier in this chapter.

After the ReportSource property is set, you can run the application. When the page is processed, the viewer is created; it processes the report specified in the report source, and then renders the output of the report page to HTML, which gets written to the response stream for the page. Figure 29.5 shows what the Web Forms Viewer looks like in action when rendering a report.

The next section describes some of the common properties used to customize the appearance and behavior of the report viewer.

Customizing the Web Forms Viewer

The first level of customization is to show or hide the main components of the report viewer. The DisplayGroupTree and DisplayToolbar properties show and hide the group tree and toolbar, respectively. PageToTreeRatio is a handy property that enables you to set the width of the group tree as a ratio to the width of the rest of the page. The default value is 6. To show or hide individual toolbar buttons, there is a collection of properties beginning with Has, such as HasExportButton and HasRefreshButton. Using these properties, you can control each button or button group on the toolbar to meet your needs. In addition, the toolbar buttons themselves are standard gif files contained in the C:\Program Files\Common Files\Business Objects\3.0\crystalreportviewers11\images\toolbar directory.

These gif files can be changed using any graphics editing program or even replaced by entirely new images assuming the filenames are kept the same. Finally, there is a style sheet associated with the Web Forms Viewer that can be overridden to change the viewer's colors, fonts, alignment, borders, and more. By default, the viewer looks for the css file in the following location:

/crystalreportviewers11/css/default.css

This location translates to the following physical path:

C:\Program Files\Common Files\Business Objects\3.0\crystalreportviewers11\css\default.css.

You can either modify this default.css file or create multiple copies of the css files, effectively having several skins for the viewer, and dynamically point the viewer to one of the css files based on a user preference. The css file location is set via the CssFilename property of the Web Forms Viewer.

By default, the viewer renders one page of the report at a time, just like the report designer would do. However, sometimes users find that it would be easier to have all the report's content contained on a single Web page. You can do this by setting the SeparatePages property to false instead of its default value of true. When this is done, the viewer renders each page under one another, effectively producing a single Web page with the entire report's data.