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.
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
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.
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.
<%@ 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); %>
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.
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:
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.
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.