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 pages 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 classs 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 objects 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 Components 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 objects 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 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. Its a good idea to create a reports folder inside the Web applications folder and store all your reports there. Then change the report location setting to .... eports. 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 users 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 servlets request object. The report viewer uses this to access the HTTP requests 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 servlets request object.

The second argument is the response object. The report viewer uses this object to access the pages response stream so it can write the HTML output of the report. Here, you simply pass the servlets 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 reports 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 forms 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 trees width can be set via the setGroupTreeWidth method. To change the formatting of the group trees text, change the CSS styles defined in the default.css file found in crystalreportviewers10/css. Alternatively, the entire group tree can be hidden by passing false to the setDisplayGroupTree function.