Using the BIRT Report Viewer

Overview

This Viewer is an AJAX based J2EE application that illustrates usingthe BIRT engine to generate and render report content.

The Web Viewer can be used to generate and render reports, and also supports more interactive features such as table of contents, exporting report content to several formats, client and server side printing, as well as report pagination. The features available will depend on what servlet mapping is used, the settings available in the web.xml file and what values are passed as parameters.

The Example Viewer can also be deployed as an Eclipse plugin in an RCP application.

The Example Viewer also ships with a tag library which can be used to provide report functionality within your existing web applications.

Servlet Mappings

The BIRT Web Viewer consist of two main Servlets, the ViewerServlet and the BirtEngineServlet. These Servlets handle three mappings: ( /frameset,/run, and /preview).

The /frameset mapping renders the report in the full AJAX viewer complete with toolbar, navigation bar and table of contents features. This mapping also generates an intermediate report document from the report design file to support the AJAX based features.
eghttp://localhost:8080/viewer/frameset?__report=myreport.rptdesign&parm1=value1

The /run mapping runs and renders the report but does not create a report document. This mapping does not supply HTML pagination, TOC or toolbar features, but does use the AJAX framework to collect parameters,support report cancelling and retrieve the report output in HTML format.
eghttp://localhost:8080/viewer/run?__report=myreport.rptdesign&parm1=value1

The /preview mapping runs and renders the report and does not generate a report document, although an existing report document can be used in which case just the render operation occurs. The output from the run and render operation is sent directly to the browser.
eghttp://localhost:8080/viewer/preview?__report=myreport.rptdesign&parm1=value1

Web Viewer Web.xml Settings

The web.xml file contains many settings used to configure the Viewer. These settings are illustrated below.

Attribute	Description
BIRT_VIEWER_LOCALE	This setting sets the default locale for the Web Viewer.
BIRT_VIEWER_WORKING_FOLDER	This is the default location for report designs.  If the report design specified in a URL parameter is relative, this path is pre-pended to the report name.
BIRT_VIEWER_DOCUMENT_FOLDER	If a report document parameter (__document) is not used, this is the location that report documents will be generated in.  If this setting is left blank, the default value “webapp/documents” will be used.  If the__document URL parameter is used and the value is relative the report document will be created in the working folder.
WORKING_FOLDER_ACCESS_ONLY	If this value is set to true, reports will only be searched for, relative to the working folder.  This prevents a user from entering a full path to a report.  Relative paths below the working folder are accessible.
BIRT_VIEWER_IMAGE_DIR	Specifies the default location to store temporary images generated by the report engine.  If this setting is left blank, the default location of webapp/report/images is used.
BIRT_VIEWER_LOG_DIR	Specifies the default location to store report engine log files.  If this setting is left blank, the default location of webapp/logs is used.
BIRT_VIEWER_LOG_LEVEL	Sets the report engine log level.  Valid values are: OFF SEVERE WARNING INFO CONFIG FINE FINER FINEST
BIRT_VIEWER_SCRIPTLIB_DIR	Specifies the default location to place Jar files used by the script engine.  These can be Jars used by script engine or jars containing event handlers written in Java.  These Jars are appended to the classpath.  If this setting is left blank the default value of webapp/scriptlib will be used.
BIRT_RESOURCE_PATH	This setting specifies the resource path used by report engine.  The resource path is used to search for libraries, images, and properties files used by a report.  If this setting is left blank, resources will be searched for in the same directory as the report.
BIRT_VIEWER_MAX_ROWS	Specifies the maximum number of rows to retrieve from a dataset.
BIRT_OVERWRITE_DOCUMENT	Specifies whether to overwrite the report document every time a report is executed.  The default is set to true.  Valid values are true and false.
BIRT_VIEWER_CONFIG_FILE	Specifies the location of the viewer.properties file.  This file contains various settings used by the viewer.
BIRT_VIEWER_PRINT_SERVERSIDE	This setting specifies whether server side printing is supported.  If set to OFF the toolbar icon used for server side printing will be removed automatically.  Valid values are ON and OFF.
HTML_ENABLE_AGENTSTYLE_ENGINE	This setting determines how BIRT styles are handled with the HTML emitter.  If set to TRUE, the BIRT engine will output the styles directly to the report and depends on the browser to implement the style calculations.  If set to FALSE the emitter will use the BIRT style engine to calculate the styles and will output the results directly to the report.

Parameters

The example viewer has a distinction between report parameters and viewer configuration parameters.  Report parameters are used by the reportdesigns and configuration parameters affect the appearance and featuresavailable to the example Viewer application.  In either case these parameters can be passed as URL parameters by entering the &parmname= valuesyntax, passed in a html form, or passed using the jsp:parm tag.  Configuration parameters by default start with a “__” prefixed to the parameter name.< /FONT>< /FONT>

Report parameters that are designated in the design as required and are not entered in one of the above methods will cause the viewer to launch a parameter entry dialog box.  Additionally the example Viewer tag library contains tags to configure and set parameters as well.

Attribute	Description
__id	A unique identifier for the viewer.
__title	Sets the report title.
__showTitle	Determines if the report title is shown in the frameset viewer.  Defaults to true.  Valid values are true and false.
__toolbar	Determines if the report toolbar is shown in the frameset viewer.  Defaults to true.  Valid values are true and false.
__navigationbar	Determines if the navigation bar is shown in the frameset viewer.  Defaults to true.  Valid values are true and false.
__parameterpage	Determines if the parameter page is displayed.  By default the frameset, run and preview mappings will automatically determine if the parameter page is required.  This setting will override this behavior.  Valid values are true and false.
__report	Sets the name of the report design to process.  This can be an absolute path or relative to the working folder (See web.xml settings).
__document	Sets the name for the rptdocument.  The document is created when the report engine separates run and render tasks, and is used to support features like table of contents and pagination.  This setting can be an absolute path or relative to the working folder (See web.xml settings).  If no document parameter is used, a unique document is created in the document folder (see web.xml settings).
__format	Specifies the desired output format, such as pdf, html, doc, ppt, or xls.
__locale	Specifies the locale for the specific operation.  Note that this will override the default locale.  Order of precedence is as follows: __locale parameter. Locale from client browser. Locale web.xml setting. Locale for the application server.
__svg	Specifies whether SVG is supported.
__page	Specifies specific page to render.
__pagerange	Specifies page range to render. Eg 1-4,7.
__isnull	Specifies that a report parameter has a null value.  Eg __isnull= Myparameter.</FONT>< /FONT>
__islocale	Specifies whether the parameter is localized.
__masterpage	Indicates that the report master page should be used or not.  Valid values are true and false.
__overwrite	This setting if set to true will force an overwrite of the existing report document. This setting will override the initial setting in the web.xml.  By default the report document is overwritten anytime the report design is changed.
__bookmark	Specifies a specific bookmark within the report to load.  The viewer will automatically load the appropriate page.
__rtl	Specifies whether to display the report in right to left format.  This setting defaults to false.
__fittopage	Specifies whether PDF generation should fit content to a page.  Valid values are true and false.
__resourceFolder	Specifies the resource folder to use.  This setting will override the default setting in the web.xml.  The resource folder is used to locate libraries, images, and resource files.