Delivering Reports in Web Applications

Report viewing is done primarily through the HTML report viewer included with the Crystal Reports Java Reporting Component. This report viewer is a control that runs inside a JSP or servlet. Its job is to get the information the report engine produces for a given page of a report and render that data to HTML format into the page's response stream.

The programmatic entry point to the report viewer is a class called CrystalReportViewer. This class is found in the com.crystaldecisions.report.web.viewer package. It can be instantiated as follows:

CrystalReportViewer viewer = new CrystalReportsViewer();

Make sure you add the class's package name in the import attribute of the page clause like this:

<%@ page import="com.crystaldecisions.report.web.viewer.*" %>

This is the main class you use to render reports to HTML. Its two main methods used to view reports are setReportSource and processHttpRequest. These methods are outlined in the following sections.

The setReportSource Method

This CrystalReportViewer object's setReportSource method is used to indicate to the viewer which report it should display. Specifically, it accepts an object that implements the IReportSource interface. The Java Reporting Component's engine supplies this object. There are generally three steps involved in setting the report source.

The first step is to create a JPEReportSourceFactory object found in the com.crystaldecisions.reports.reportengineinterface package. As the name implies, this object's job is to create report source objects. This object has one relevant method: createReportSource. Its definition is as follows:

IReportSource createReportSource(object reportPath, Locale userLocale)

The reportPath argument should be a string consisting of the filename of the report file (.rpt). With the Java Reporting Component, the path from where the report file should be loaded is configured in the CrystalReportEngine-config.xml file. This XML configuration file has a <reportlocation> element that indicates the location of the report files relative to the location of the config file. The default value for the reportlocation is ..\.., which (if the config file was in the classes folder as outlined in the previous section) would point to the webApplicationFolder folder. It's a good idea to create a reports folder inside the Web application's folder and store all your reports there. Then change the report location setting to ..\..\reports. Then when reports are referenced in the call to createReportSource, you only need to pass the name of the report, not the folder location.

The second argument to createReportSource is a Locale object. Generally, you should pass in request.getLocale(). This means that whatever the user's locale is, it is passed down to the report engine so any locale-specific formatting can be applied.

The processHttpRequest Method

After the viewer is told which report it needs to view, the only other method left to call is the processHttpRequest method. This method kicks off the actual report processing and renders the report to HTML. Its definition is as follows:

void processHttpRequest(HttpServletRequest request,                         HttpServletResponse response,                         ServletContext context,                         Writer out)

The first argument passed in is the current servlet's request object. The report viewer uses this to access the HTTP request's form data where the viewer holds its state information such as what page it was showing, what level of drill-down, and so on. Also stored in the form data is the piece of data that indicates what action is to be performed. For example, the user might have clicked the Next Page button, or might have also drilled down. You simply pass in the servlet's request object.

The second argument is the response object. The report viewer uses this object to access the page's response stream so it can write the HTML output of the report. Here, you simply pass the servlet's response object.

The third argument is the servletContext, which is used to access the servlets container. Generally, you pass getServletConfig().getServletContext() for this argument. The final argument is a Writer. You generally pass null here unless you want to provide your own Writer.

Listing 28.1 shows these concepts all brought together in a JSP page that displays a report.

Listing 28.1. Viewing a Report in HTML

<%@ page contentType="text/html;charset=UTF-8"     import="com.crystaldecisions.reports.reportengineinterface.*,             com.crystaldecisions.report.web.viewer.*"  %> <% // name of report file String reportFile = "Income_Statement.rpt"; // create the JPEReportSourceFactory JPEReportSourceFactory rptSrcFactory = new JPEReportSourceFactory(); // call the createReportSource method Object reportSource = rptSrcFactory.createReportSource(reportFile,                                                        request.getLocale()); // create the report viewer CrystalReportViewer viewer = new CrystalReportViewer(); // set the report source viewer.setReportSource(reportSource); // tell the viewer to display the report viewer.processHttpRequest(request,                           response,                           getServletConfig().getServletContext(),                           null); %>

The output of this page is shown in Figure 28.2. All content for the report consists of HTML elements, keeping all formatting and layout preserved. Every once in a while you will find a discrepancy in the report output between the designer and the HTML viewer, but the advantages of the HTML viewer generally outweigh the disadvantages. Besides drilling down or hyperlinking from the report's main content, a toolbar along the top provides a way for the end user to interact with the report. Buttons for page navigation as well as printing and exporting are present. When a command is performed by the user such as navigating to the next page or drilling down, the report viewer using a JavaScript function causes a form post to occur back to the same page. Both the current state and the new command are sent as part of the form's post data. The JSP or servlet reruns and the new state of the report is again rendered back to HTML.

Figure 28.2. This is the HTML report viewer in action.

There is a collection of methods that the CrystalReportViewer object exposes that can be used to customize how the viewer looks and behaves. For the full list of methods, consult the API documentation; however, the following sections cover some of the more useful types of customizations.

Customizing the Toolbar

Each button or set of buttons on the report viewer toolbar can be individually turned off and on. These are done by a set of simple methods that accept a Boolean argument. They are listed here:

• setHasToggleGroupTreeButton(boolean)

• setHasExportButton(boolean)

• setHasPrintButton(boolean)

• setHasViewList(boolean)

• setHasRefreshButton(boolean)

• setHasPageNavigationButtons(boolean)

• setHasGotoPageButton(boolean)

• setHasSearchButton(boolean)

• setHasZoomFactorList(boolean)

• setHasLogo(boolean)

Finally, the entire toolbar can be turned off by calling setDisplayToolbar(boolean). If the toolbar is turned off, the user does not have a way to interact with the report such as navigating pages. To facilitate this, there are other methods on the CrystalReportViewer object that can be called to drive the page navigation, including showFirstPage, showPreviousPage, showNextPage, showLastPage, and showNthPage. Similar methods exist to re-create the functionality of most of the other buttons as well. In general, the methods related to toolbar customization are almost self-explanatory.

Customizing the Group Tree

The group tree's width can be set via the setGroupTreeWidth method. To change the formatting of the group tree's text, change the CSS styles defined in the default.css file found in crystalreportviewers11/css. Alternatively, the entire group tree can be hidden by passing false to the setDisplayGroupTree function.