Chapter 2. Programming Guide

2.1. Introduction to Report Viewer

2.1.1. Introduction

All reports created by Report Designer can be saved in various static file formats that can be viewed later. These formats include DHTML and PDF. In addition, Report Designer provides the option of saving a report as a .rpt file.

Report Viewer is an applet that enables you to view and manipulate a report dynamically through a web browser. Report Viewer reads the file (in .rpt format) as outputted by Report Designer or Report API and displays the report. The small size of the file makes it suitable to distribute the report over the web. The data is encrypted while being transferred from EspressManager to Report Viewer. Therefore, there is a degree of security to sensitive information.

Files in the .rpt format are viewed using Report Viewer. When a web page that contains a .rpt file is viewed using a browser, the most up-to-date data will be obtained automatically by Report Viewer (via EspressManager). Thus a .rpt file can be used to supply up-to-the-minute reports to users in real time.

You can navigate to different sections and pages of the report by using Report Viewer. There are built-in callback mechanisms that would allow users to click on a data element to jump to a related URL. Report Viewer is written in pure Java, thus, runs on all platforms that support Java. Report Viewer also supports scheduled refresh (whereby a report’s data is updated at regular intervals specified by the Designer) and parameter serving where a report’s parameters are provided at load time.

2.1.2. Launching Report Viewer

To launch the Report Viewer, you can either embed Report Viewer in an applet or simply click on the Preview tab in the Report Designer.

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

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

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

    </applet>

The parameter value of filename specifies the name of the file that contains the report. The filename value can also be specified by a URL. For example, you can prefix it by http:// for accessing a remote data file. When viewed in Report Viewer, the .rpt file will connect to the data source specified, dynamically fetch the data and generate the report.

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

2.1.3. The Report Viewer Parameters

Without using Report Designer, you can also pass data via parameters to Report Viewer applet. That is, you can use Report 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:

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.

ParameterServer:

Port number of the parameter server which pushes the data into the client.

RefreshInterval:

Specifies the interval in seconds to refresh the data (i.e. getting the data from the data source).

FileName:

Specifies the name of the .rpt file.

ReportData:

Specifies the report as a string.

SourceDB:

Specifies the database information.

SourceFile:

Specifies the data file information.

SourceData:

Specifies the data information.

ReportType:

Specifies the report type.

Aggregation:

Specifies the Aggregation Method.

ColInfo:

Sets the column mapping.

RowBreak:

Specifies the column(s) to be used as Row Breaks.

ColumnBreak:

Specifies the column to be used as Column Break.

ColumnBreakValue:

Specifies the column to be used as the values for the Column Break columns.

PrimaryKey:

Specifies the column to be used as Primary Key.

MasterKey:

Specifies the column(s) to be used as Master Key.

EspressManagerUsed:

If false, EspressManager is not used. The default is true.

RefreshData:

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

ExportEnabled:

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

Example: With the parameter RefreshInterval you can insert the following line:

<PARAM name="RefreshInterval" value="60">

In the above example, the Report Viewer applet will fetch data from the specified data source (with the help of EspressManager) and redraw the report every 60 seconds - all transparently. It is useful for accessing databases which are updated frequently.

Note that when specifying parameters that can have multiple values (or needs to be have multiple values), the separator is a space ( without the double quotes). For example:

<PARAM name="RowBreak" value="0 1 2">

In the above example, the Row Break is set on Column 0, Column 1 and Column 2 of the Column Mapping (i.e. the first three columns). The values for the parameter have a space ( without the double quotes) separating them.

2.1.4. Specifying the Data Source for Report Viewer

2.1.4.1. Data Read From Database

Here is a sample HTML code that uses Report Viewer to view a report with data extracted from a database:

    <applet code = "quadbase.reportdesigner.ReportViewer.Viewer.class" width=640 height=480>
    <PARAM name="sourceDB" value="jdbc:odbc:DataSource ,
        sun.jdbc.odbc.JdbcOdbcDriver,
        username ,
        password ,
        select * from products">

    <PARAM name="ColInfo" value="0 1 3">
    <PARAM name="ReportType" value="SummaryBreak">
    <PARAM name="RowBreak" value="0">
    <PARAM name="Aggregation" value="SUM">
    </applet>

The arguments of ColInfo specify the mapping for the report. If you want more information, please see the chapter on Column Mapping in Introduction to EspressReport API.

The argument ReportType specifies the type of report to be displayed and it can be one of:

  1. SimpleColumnar

  2. CrossTab

  3. MasterDetails

The argument RowBreak specifies the column on which the row break is applied.

The argument Aggregation specifies the aggregation method applied and it can be one of:

  1. NONE

  2. SUM

  3. MAX

  4. MIN

  5. COUNT

  6. AVG

  7. FIRST

  8. LAST

  9. SUMSQUARE

  10. VARIANCE

  11. STDDEV

  12. COUNTDISTINCT

2.1.4.2. Data Read From a Data File

This HTML code generates a report using data from a data file.

<applet code = "quadbase.reportdesigner.ReportViewer.Viewer.class" width=640 height=480>
<PARAM name="sourceFile" value="http://.../test.dat">
<PARAM name="ColInfo" value="1 0 2 3">
<PARAM name="ReportType" value="SimpleColumnar">
</applet>

2.1.4.3. Data Read From Argument

It is possible to have Report Viewer read in data directly from the HTML file itself rather than from a data file or database.

    <applet code = "quadbase.reportdesigner.ReportViewer.Viewer.class" width=640 height=480>
    <PARAM name="SourceData" value="int, string, int |
        value, name, vol |
        10, 'John', 20 |
        3, 'Mary', 30 |
        8, 'Kevin', 3 |
        9, 'James', 22">

    <PARAM name="ColInfo" value="1 0 2">
    <PARAM name="ReportType" value="SimpleColumnar">
    </applet>

The format for the parameter SourceData is the same as the data file format, except that each line is ended by a vertical bar |.

2.1.5. Using Report Viewer

Using Report Viewer, you can browse through the report using the Pop-Up Menu. Right clicking on the report displays a Pop-Up Menu which can be used to traverse the report. The pop-up Menu displays various options:

Back:

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

Section:

Contains several 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 several 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 option either shows or hides the navigation toolbar at the bottom of the Viewer window.

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

  1. Left click on 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 in the browser to return to the previous report).

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

2.1.6. Parameter Server

The Parameter Server allows EspressReport Viewer to listen for requests from the specified port using TCP/IP and update the data dynamically. The syntax is

<applet code = "quadbase.reportdesigner.ReportViewer.Viewer.class" width=640 height=480>
<PARAM name="ParameterServer" value="machine:portno">
</applet>

For security reasons, the machine is usually the same as the web server machine. Therefore, you can leave machine empty (i.e. value=":portno"). For more information about the parameter server, please refer to Appendix 2.A - Parameter Server.

2.1.7. Connecting to EspressManager

2.1.7.1. EspressManager Running as Application

EspressManager runs primarily as an application. If you wish to use Report Viewer to connect to the EspressManager running as 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 Report Viewer connect to the EspressManager running on Machine and listening on PortNumber.

2.1.7.2. EspressManager Running as Servlet

EspressManager can be run as a servlet as well. If you wish to use the Report 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 parameterss to your HTML code will make the Report Viewer connect to the EspressManager at http://Machine:PortNumber/EspressReport/servlet.

2.1.8. Swing Version

A JFC/Swing version of the Report Viewer can also be used to refer to SwingReportViewer.jar instead of ReportViewer.jar in EspressReport/lib directory.

2.1.9. Exporting from Viewer

This section pertains to exporting from the Viewer in an Applet only. When using the Report 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 information 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, two lines of code must be added:

Viewer viewer = new quadbase.reportdesigner.ReportViewer.Viewer();
Component comp = viewer.getComponent(report);
viewer.setExportServlet("http://host:port/servlet/ViewerExportServlet");
viewer.setDynamicExport(true, "host", port, "servlet/");

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 these options will result in a pop-up browser window that contains the streamed content of the report.