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 on the client would cause the client to quickly run out of memory.

For situations like this, EspressReport provides another viewer called Page Viewer. Instead of loading the entire report on 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 on 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 Page Viewer, you can embed the Viewer 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 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 the lib/ directory of the EspressReport Installation to some 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 Report Designer. When previewing a report with a large amount of data, the report can be loaded in a Page Viewer window. This allows users to preview and view the entire report without loading all the data in 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, EspressManager is not used. The default is true. If Page Viewer is being used to run a report template, EspressManager must be used. If a view file is used, then 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 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 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 the various options:

Back:

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

Section:

Contains various options to navigate 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 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 onto a single file.

Generate HTML (Multiple Pages):

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

Generate DHTML (Single Page):

Export the report to DHTML onto a single file.

Generate DHTML (Paginated Single Page):

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

Generate DHTML (Multiple Pages):

Export the report to DHTML onto 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 single 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, Page Viewer 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 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, 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 is run primarily as an application. If you wish to use Page Viewer to connect to EspressManager running an application, you will have to add the following tags to your HTML code:

<PARAM name="server_address" value="someMachine">
<PARAM name="server_port_number" value="somePortNumber">

Adding the above params to your HTML code will make Viewer connect to EspressManager running on someMachine and listening on somePortNumber.

2.2.6.2. EspressManager Running as Servlet

EspressManager can be run as a servlet as well.If you wish to use Page Viewer to connect to 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://someMachine:somePortNumber"> 
<PARAM name="servlet_context" value="EspressReport/servlet">

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

2.2.7. Swing Version

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

2.2.8. Exporting from Viewer

This section pertains to exporting from the 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(OutputServerGenerate) 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 at <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 OutputClientGenerate. All of these options will result in a pop-up browser window that contains the streamed content of the report.