The Viewer performs three distinct operations, of which one is internal and not visible to your application:
You can use a full-feature viewer frameset that handles parameter entry, Table of Contents, export to CSV and HTML pagination. Or, you can supply the parameter values and simply run the report to produce a simple HTML or PDF output page.
The Report Viewer provides a number of URLs that control its behavior. The Report Viewer provides two modes of operation as given by two servlet mappings.
|frameset||Displays a frameset that contains the report and additional AJAX components for retrieving Table of Contents, exporting to CSV, parameter entry and paging controls.|
|run||Runs the report and displays the output as a stand-alone HTML page, or as a PDF document.|
The servlet mapping names are case-sensitive.
The run servlet mapping runs a report given a set of report parameters, and returns the report as an HTML page or PDF document. This servlet mapping does not provide a frameset. Use this option if you want the report to appear as a stand-alone page or if PDF output is required. Parameters must be handled in one of three ways:
If your report has a required parameter with no default value, the parameter entry screen will be displayed automatically.
The run report URL is of the form:
See below for a list of available viewer command options.
command provides additional UI to work with a report. Use this URL if
your report contains parameters, and you want the viewer to display a
UI so the user can enter parameter values. Using the
command also allows for HTML pagination.
The frame-based viewer displays a frameset that contains the report and controls for the following functions:
The parameters dialog displays a form for entering the parameters (if any) for a report. It contains a Run Report button that runs the report. The report then appears in the report frame. The user can refine the report simply by modifying parameters in the parameter frame and again by clicking on Run Report.
The viewer URL is of the form:
See below for a list of available command options. The command options allow you to control which of the three frames appear in the resulting Web page.
When you issue this command, the viewer will do one of two things:
The run and the frameset viewer operations both take a set of options which include report parameters. Report parameters are defined within the report design. They appear in the URL using their internal names, not display names. Viewer options pass information to the Report Viewer Web application. Viewer options start with a double underscore to differentiate them from report parameters. Option names and values must be encoded for use in a URL. For example:
In the above:
The available viewer options include:
|__format||The output format||html or pdf||html||N||Y|
|__isnull||Identifies that a report parameter has a null value||Parameter name||None. Required.||N||Y|
|__locale||Report locale||Java locale value such as en, en-us or ch-zh.||JVM locale||Y||Y|
|__report||The path to the report design.||None. Required.||Y||Y|
|__document||The path to the report document.||None. Required.||Y||N|
|reportParam||Report parameter.||As specified in the report design.||As specified in the report design.||Y||Y|
Case-sensitivity of the options varies:
If the URL contains a misspelled option name, or the names of report parameters are in the wrong case, then the viewer silently ignores the parameter.
The type of output to produce: either HTML or PDF. Values are case-insensitive. If a value other than PDF is provided, the HTML format is produced.
Report parameters can take a value, or can be null. Hereby, "null" means the database definition: the value is unknown. By definition, date and numeric report parameters have a null value if the report parameter is provided in the URL, and the value is blank. However, string report parameters have an ambiguity: is an empty value to be considered blank (a string whose value is ""), or null? Since blank is used more often, the Business Analysis and Reporting Component interprets an empty report parameter value as blank.
To say a string parameter is null, just write:
While this option is primarily for string report parameters, it works just as well for other report parameter types as well. See the Report Parameters section below for additional details.
option to specify both the locale for report parameter values, and the
locale for the report output. The locale must be a valid Java locale
en-us. If you do not specify a locale, it defaults
to the locale set in the Java virtual machine (JVM).
Values are case-insensitive.
The __report option names the report design to run. It can be an absolute or relative file name. If relative, the looks in the directory specified in the BIRT_VIEWER_WORKING_FOLDER property in the viewer's web.xml file. The file search rules are:
The __document option names the report document to run with the frameset mapping. This file is the intermediate file when run and render are separate phases. It can be an absolute or relative file name. If relative, the looks in the directory specified in the BIRT_VIEWER_WORKING_FOLDER property in the viewer's web.xml file. The file search rules are:
Report parameters can be Boolean, Number, Date, Float or String. The values are defined as follows:
|Data Type||Value Encoding||Notes|
|Boolean||true, false||Must use the value true for a true value, all other values (including 1) are treated as false. (Uses the Java Boolean.parse() method for parsing.) Values are case-insensitive.|
|Number||Floating point number with a locale-specific decimal separator.||Must not include a thousands separator, or extra characters such as a currency symbol. Uses the Java java.text.DecimalFormat class to parse the number.|
|Date||Locale-specific date format.||Uses the Java java.text.SimpleDateFormat class to parse the date.|
The rules for a given parameter foo are determined by the first rule below that takes effect:
The report definition provides two properties for report parameters that influence parameter validation. First, the allowNull property determines if a report parameter can be null. If a report parameter has a null value, but the allowNull property is false, then the Stardust Report Engine will raise an error.
Second, string report parameters have a allowBlank property. If the report parameter has a blank value, and allowBlank property is false, the Stardust Report Engine will raise an error.
If an error occurs during the operation, an error page will appear.