2.2. Introduction to Page Viewer

2.2.1. Introduction

The Report Viewer component offers users the capability of viewing and manipulating a report through a Web browser. The viewer loads the report template on the client and shows it to the user with the latest data. Report Viewer, however, is not the ideal deployment solution when the report contains a large amount of data. In these situations, loading the entire report at the client would cause the client to quickly run out of memory.

For situations like these, EspressReport provides another viewer called Page Viewer. Instead of loading the entire report at the client, Page Viewer employs a page serving technology that allows the client to load only one page of the report at a time. This allows the report to load faster and conserves the client memory.

Page Viewer works by exporting the report into a series of page (.page) files that contain the drawing information for a set of pages in the report. The .page files are then loaded in the viewer at the client. Users running with EspressManager can directly pass in a report template as part of Page Viewer code. The report will be exported on the server with the latest data and the client will load the .page files. Users running without EspressManager can export the report in view format either from the API or Report Designer. These exported files can be loaded directly in Page Viewer without the EspressManager.

2.2.2. Launching Page Viewer

To launch the Page Viewer, you can embed it in an applet using a .rpt file (EspressManager) or an exported view (.view) file (with or without EspressManager). Page Viewer can also be used to load a report directly from the Preview window in Report Designer.

To embed the Page Viewer in an applet, simply use the following code:

    <applet codebase = ".." code = "quadbase.reportdesigner.PageViewer.Viewer.class" width = 100% height = 100% archive="PageViewer.jar">

        <PARAM name = "filename" value = "yourReport.rpt">

    </applet>

The parameter value of filename specifies the name of the file that contains the report. If you are running Page Viewer with EspressManager on the back-end, you can specify the name of a report template. You can also use an exported view file for this parameter. When using a view file with Page Viewer, you do not have to have EspressManager running. The filename value can also be specified by a URL. For example, you can prefix it by http:// for accessing a remote data file.

You may also use Page Viewer in an application. To do so, simply use the following code to get a java.awt.Component Object.

quadbase.reportdesigner.PageViewer.Viewer.getComponent(java.awt.Frame frame, java.lang.String fileName, long bufferTimeInSec)

In addition to passing in the template file (or view file), you can also pass in a QbReport object. Note that instead of using the Viewer class, you would be using the ViewerAPI class.

quadbase.reportdesigner.PageViewer.ViewerAPI.getComponent(java.awt.Frame frame, QbReport report, long bufferTimeInSec, java.lang.String securityLevel);

The above methods are the simpliest of all methods for getting Page Viewer as a Component. For more information about the parameters for this constructor or information on other methods related to Page Viewer, please consult the EspressReport API Specification.

[Note]Note

On the server side, you will need to copy the PageViewer.jar file from lib/ directory of the EspressReport Installation to a directory of your web server that is accessible by the web client.

2.2.2.1. Launching from Report Designer

Page Viewer can also be invoked from the Report Designer. When previewing a report with large amount of data, the report can be loaded into a Page Viewer window. This allows users to preview and view the entire report without loading all the data into memory. For more information about this feature, please see Section 1.6.2.4 - Using Page Viewer.

2.2.3. The Page Viewer Parameters

Without using Report Designer, you can also pass data via parameters to Page Viewer applet. That is, you can use Page Viewer to directly view a data file, or pass the data directly in the form of lines of data in the HTML code. The following is a list of parameters:

Page Parameters

comm_protocol:

The protocol to be used, in case there is a firewall or if you wish to connect to EspressManager running as a servlet.

comm_URL:

The URL to connect to EspressManager, in case of a firewall or if EspressManager is running as a servlet.

servlet_context:

The context to connect to EspressManager running as a servlet.

server_address:

The IP address of the EspressManager connection.

server_port_number:

Port number of the EspressManager connection.

server_hosts:

Any other name(s) that the EspressManager host may can be specified by using a comma as a separator.

FileName:

Specifies the name of the .rpt file.

EspressManagerUsed:

If false, the EspressManager will not be used. The default is true. If the Page Viewer is being used to run a report template, the EspressManager must be used. If a view file is used, then the EspressManager does not have to be running.

BufferTime:

The time, in seconds, that controls how often to get new pages from the EspressManager. It looks at the local version of the .page file (if available). If the time since it was last updated exceeds the bufferTimeInSec parameter, the new version of the page is requested again from the EspressManager. Otherwise, it uses the local version of the .page file. If the local version of the .page file does not exist, it will get the page from the EspressManager.

DataHintOffsetX:

When the user moves the mouse over a data point (a bar on a bar graph or a point on a line graph) on a chart, a hint box that shows the details of the data point is shown. This parameter sets the horizontal offset position of the hint box relative to the data point.

DataHintOffsetY:

When the user moves the mouse over a data point (a bar on a bar graph or a point on a line graph) on a chart, a hint box that shows the details of the data point is shown. This parameter sets the vertical offset position of the hint box relative to the data point.

DataHintBgColor:

When the user moves the mouse over a data point (a bar on a bar graph or a point on a line graph) on a chart, a hint box that shows the details of the data point is shown. This parameter sets the background color of the hint box.

DataHintFontColor:

When the user moves the mouse over a data point (a bar on a bar graph or a point on a line graph) on a chart, a hint box that shows the details of the data point is shown. This parameter sets the font color of the hint box.

DataHintFont:

When the user moves the mouse over a data point (a bar on a bar graph or a point on a line graph) on a chart, a hint box that shows the details of the data point is shown. This parameter sets the font type of the hint box.

Printing:

Valid values: "true" | "false"

Sets whether the print option is shown in the pop-up menu.

RefreshData:

Valid values: "true" | "false"

If false, report cannot be refreshed.The default is true.

PopupMenu:

Valid values: "true" | "false"

Sets whether the pop-up menu is shown.

EnableExport:

Valid values: "true" | "false"

If false, report cannot be exported.The default is true.

ShowDataHint:

Valid values: "true" | "false"

Sets whether to show a data hint box when mouse over a data point in a chart.

ShowLinkHint:

Valid values: "true" | "false"

Sets whether to show a data hint box when mouse over a hyperlink.

Example: With the parameter BufferTime, you can insert the following line:

<PARAM name="DataHintBgColor" value="ff00aa">

2.2.4. Using Page Viewer

Using the Page Viewer, you can browse through the pages of the report using the pop-up menu. Right clicking on the report displays a pop-up menu that can be used to traverse the report. The pop-up menu shows various options:

Back:

Go back to the previous report. This option is shown when you click on a hyperlink.

Section:

Contains various options to navigate through the various sections.

First Section:

Go to the first section.

Previous Section:

Go to the previous section.

Next Section:

Go to the next section.

Last Section:

Go to the last section.

Page:

Contains various options to navigate through the various pages.

First Page:

Go to the first page.

Previous Page:

Go to the previous page.

Next Page:

Go to the next page.

Last Page:

Go to the last page.

Output:

Contains various formats to output the report to.

Generate HTML (Single Page):

Export the report to HTML as a single file.

Generate HTML (Multiple Pages):

Export the report to HTML as multiple files, one file per page.

Generate DHTML (Single Page):

Export the report to DHTML as a single file.

Generate DHTML (Paginated Single Page):

Export the report to DHTML as a single file, with breaks to simulate pages.

Generate DHTML (Multiple Pages):

Export the report to DHTML as multiple files, one file per page.

Generate PDF:

Export the report to PDF.

Generate CSV:

Export the report to CSV.

Generate EXCEL (XLS):

Export the report to Excel (xls file).

Generate EXCEL 2007 (XLSX):

Export the report to Excel 2007 (xlsx file).

Generate TXT:

Export the report to TXT.

Generate RTF:

Export the report to RTF.

Generate XML (Data + Format):

Export the complete report to XML.

Generate XML (Pure Data):

Export the report data only to XML.

Print:

Print the report.

Refresh:

Refresh the data from the data source.

Go To:

Go to the specified page and section.

Zoom:

Specify the zooming factor to be applied to the report.

Sort by (ascend):

Sort the report based on a selected column's ascending values.

Sort by (descend):

Sort the report based on a selected column's descending values.

Show/Hide Report Toolbar:

This either shows or hides the Navigation toolbar at the bottom of the viewer window.

In addition to the pop-up menu, you can also:

  • Left click to jump to the hyperlink associated with the cell (note that this creates a new browser window if the associated URL is NOT a .rpt file. Users cannot use the Back button on the browser to return to the previous report).

  • Run the mouse over a cell containing a hyperlink to see the Hint text associated with the link.

2.2.5. Buffer Time

A problem working with the view (.view) and page (.page) files associated with Page Viewer is that while saving memory and boosting performance by caching the report page by page on a file system, the Page Viewer's files data might become obsolete in time. In other words, they might not reflect the latest report data. The solution to this is to have a mechanism for updating the Page Viewer files during certain time intervals.

Page Viewer provides the mechanism to adjust the time elapsed until a new view file needs to be fetched from the server. This time interval, also known as the Buffer Time, can be adjusted by setting the parameter BufferTime in the Page Viewer applet. Simply pass in the buffer time in seconds as the value to the parameter BufferTime. The Page Viewer will then fetch new pages whenever the current version of the VIEW file becomes older than the specified buffer time.

Also, the Page Viewer has a built-in mechanism that automatically eliminates the old view and page files when they have not been updated for three or more days.

2.2.6. Connecting to EspressManager

2.2.6.1. EspressManager Running as Application

EspressManager runs primarily as an application. If you wish to use the Page Viewer to connect to the EspressManager running an application, you will have to add the following tags to your HTML code:

<PARAM name="server_address" value="Machine">
<PARAM name="server_port_number" value="PortNumber">

Adding the above parameters to your HTML code will make the Page Viewer connect to the EspressManager running on Machine and listening on PortNumber.

2.2.6.2. EspressManager Running as Servlet

EspressManager can be run as a servlet as well. If you wish to use the Page Viewer to connect to the EspressManager running as servlet, you will have to add the following tags to your HTML code:

<PARAM name="comm_protocol" value="servlet"> 
<PARAM name="comm_URL" value="http://Machine:PortNumber"> 
<PARAM name="servlet_context" value="EspressReport/servlet">

Adding the above params to your HTML code will make the Page Viewer connect to the EspressManager at http://Machine:PortNumber/EspressReport/servlet.

2.2.7. Swing Version

A JFC/Swing version of the Page Viewer can also be used to refer to SwingPageViewer.jar instead of PageViewer.jar in EspressReport/lib directory.

2.2.8. Exporting from Viewer

This section pertains to exporting from the Page Viewer in an applet only. When using the Page Viewer API to create a Component that displays a report, the user can right click on the Component to launch a pop-up menu with various options. One of the options (Output → Server → Generate) is for exporting the report to different file formats. This will result in creating the exported file on the server side. However, there is an API feature that utilizes a server side Java servlet to stream back the exported content to the client's browser. The following describes how to use this feature:

First, you need to deploy the servlet that will stream the exported file back to the client side. This servlet, called ViewerExportServlet, is located in <espress-report-install-dir>/ViewerExport/ViewerExportServlet.java. Simply compile the servlet and deploy it in your Servlet container.

Next, in the code that retrieves the report Component, four lines of code need to be added:

Viewer viewer = new quadbase.reportdesigner.PageViewer.Viewer();
Component comp = viewer.getComponent((Applet)null, reportTemplate, 0);
viewer.setExportServlet("http://host:port/servlet/ViewerExportServlet");
viewer.setDynamicExport(true, "host", port, "servlet/");

where reportTemplate is a string containing the name and path of the report template file. You can also pass in a QbReport object using the following code:

ViewerAPI viewer = new quadbase.reportdesigner.PageViewer.ViewerAPI();
Component comp = viewer.getComponent((Applet)null, report, 0, null);
viewer.setExportServlet("http://host:port/servlet/ViewerExportServlet");
viewer.setDynamicExport(true, "host", port, "servlet/");

where report is a QbReport object.

The argument for the setExportServlet method is the URL location of your deployed ViewerExportServlet. Please see the javadoc specification for more details about the arguments of these two methods.

Then, when the user views the report Component, there will be new options under Output → Client → Generate. All of these options will result in a pop-up browser window that contains the streamed content of the report.