Render a formatted report from a report design by calling the method IRunAndRenderTask.run( ). Render a formatted report from a binary report document by calling the method IRenderTask.render( ).
Setting up the rendering options
Before rendering a report to an output format, the application must set options that determine features of the output. The options must specify either an output file name or a stream. Other settings, such as the type of HTML to generate, are optional. BIRT supports two types of HTML output, HTML and embeddable HTML. Embeddable HTML is suitable for including inside another web page. This format contains no header information nor the <body> or <html> tags.
The application uses a rendering options object to set the output options on an IRunAndRenderTask or an IRenderTask object. Format-specific rendering options classes implement IRenderOption and extend RenderOption. The rendering options class for the Excel format is EXCELRenderOption, for the HTML format is HTMLRenderOption, and for the PDF format is PDFRenderOption. All other output formats use the RenderOption class.
After creating the rendering option object, call the task’s setRenderOption( ) method. This method takes an IRenderOption object as an argument. Use the setRenderOption( ) method on an IRenderTask or an IRunAndRenderTask object. This method performs no function on an IRunTask object as this task does not render output. Listing 5‑11 includes code to set the rendering option for HTML.
To apply a rendering setting, use setter methods on the rendering option object. These objects also have getter methods that retrieve render settings. Common option settings are a base URL for hyperlinks, an action handler, an image handler, output format, and supported image output formats.
The supported image formats setting is used for extended report items such as charts or custom extended items. The final rendering environment for the report, such as the browser for a report in HTML format, affects this option value. To set supported formats, use setSupportedImageFormats( ) with a String argument containing a list of the supported image formats. The image formats are standard types, such as GIF, JPG, PNG, and SVG. Semicolons separate the items in the list. The method getSupportedImageFormats( ) returns a String of the same format.
Understanding HTML rendering options
Before generating an HTML report that uses images on disk or creates images or charts in a report, the application must provide additional settings. The HTMLRenderOption class provides many ways to customize the emitted HTML. The following list describes some of the commonly used options and how the options interact with each other:
Image directory. Many reports include either static or dynamic images. For example, charts are dynamic images. HTML reports place all these images in a defined location. To set this location, call the setImageDirectory( ) method.
Base image URL. For web deployment, such as a WAR file, the images created in the image directory must be available to a user’s web browser. Provide the engine with a URL prefix to apply to the image directory. To set the URL, use the setBaseImageURL( ) method, as shown in Listing 5‑2.
Image handler. Use the setImageHandler( ) method to set up an image handler, as described earlier in this chapter.
Embeddable HTML. Call the setEmbeddable( ) method with the argument, true, to set this option. The embeddable produced HTML does not have <html> and <body> tags.
Right‑to‑left generation. To set the HTML emitter to generate content right to left, call the setHtmlRtLFlag( ) method with the argument, true.
Title tag. Use the setHtmlTitle( ) method to write a <title> tag to the produced HTML. This title appears in the title bar of the browser and in the tab on a multi-tabbed browser window.
Master page content. In a BIRT report design, the developer uses the master page to set up page sizes, header and footers. These settings affect the produced HTML. To suppress the master page content, call the setMasterPageContent( ) with the argument, false. The master page content setting affects the results of setting paginated HTML and fixed layout.
Floating footer. By default, the master page footer appears directly below the content of each HTML page. Pass the argument, false, to the setPageFooterFloatFlag( ) method to force the footer to the bottom of a fixed‑size master page. This setting adds a div statement with a height attribute to the produced HTML.
Master page margins. Master page margins affect the appearance of the HTML output if the report uses fixed layout or if the value, true, is the argument to the setOutputMasterPageMargins( ) method.
Paginated HTML. When rendering the report in HTML, the engine supports paginating the results. The report design’s master page defines the size of the page and the content of its page headers and footers. To display the entire or partial report as a single HTML page, call the setHtmlPagination( ) method with the argument, false. In this case, setting a render task page range of 5-7 renders pages 5 to 7 as one HTML page. Header and footer information appear several times within this HTML page if you choose to display master page content. For your application to support pagination, you need to set up pagination controls similar to the example Web Viewer.
Fixed or automatic layout. By default, BIRT generates tables with columns that are fixed in size. When the user changes the width of the browser window, the column widths do not change. BIRT also supports automatic layout, in which column widths adjust according to the width of the window. Fixed layout produces reports with a consistent layout, but this choice can increase rendering time. The table-layout:fixed attribute is applied to all tables. Appropriate div statements set column widths and padding. The div settings are also applied if master page content is used. To change this setting, use the setLayoutPreference( ) method. Pass the LAYOUT_PREFERENCE_AUTO or LAYOUT_PREFERENCE_FIXED value as its argument.
Style calculation. The setEnableAgentStyleEngine( ) method provides the developer control over how the styles are calculated. Passing a value of true to this method emits the styles directly to the produced HTML. In this case, the browser performs the style calculations. Passing a value of false to the method causes the emitter to use the BIRT style engine to do the calculations. As with the fixed or automatic layout setting, this setting affects the consistency of the report’s appearance.
Base URL. Most BIRT report items have a hyperlink property. When building this hyperlink in the report designer, the report developer uses a URL, an internal bookmark, or a drill-through operation. The report design stores the results of the design session. The setBaseURL( ) method defines the base URL to prefix to the hyperlinks built using the designer. Use this setting for applications deployed in a web environment.
Action handler. The emitter handles hyperlink, bookmark, and drill‑through actions. When rendering the report as HTML, BIRT uses the HTMLActionHandler class to determine how to build the hyperlink for these actions. The HTMLActionHandler class implements the IHTMLActionHandler interface. If the default HTMLActionHandler does not meet your needs, use a custom implementation of IHTMLInterface. To set up the new action handler, use the setActionHandler( ) method.
The HTMLRenderOption class provides equivalent getter methods for the setter methods described in the previous list.
How to configure properties for a report in HTML format
The code sample in Listing 5‑11 shows the use of rendering options on an IRunAndRenderTask object to set report parameter values, the output format of the report, and the output file name. The variable, engine, is a ReportEngine object. The variable, runnable, is an object of type IReportRunnable. The variable, name, is the name of the report design.
Listing 5‑11 Configuring properties on an IRunAndRenderTask object
The EXCELRenderOption class provides the following methods to modify the appearance of the generated spreadsheet:
setHideGridlines( ) uses a boolean value of true or false to hide or show gridlines in the spreadsheet.
setOfficeVersion( ) sets the compatibility level of the spreadsheet. Valid values for the String parameter are office2003 and office2007. The default value is office2003.
setWrappingText( ) uses a boolean value of true or false to set or unset text wrapping in cells in the spreadsheet.
The EXCELRenderOption class provides equivalent getter methods to retrieve the current values of the options.
Using generic methods to access rendering options
The RenderOption class provides getter and setter methods for accessing the most commonly used rendering options. For example, this class provides the getOutputFileName( ) and setOutputFileName( ) methods to get and set the file name of rendered report. RenderOption also provides fields to identify the options. An application accesses the less commonly used options by calling the following generic methods, inherited from TaskOption, using a RenderOption field as an argument:
getOption( )
This method returns an Object containing the option value. For boolean or int values, the returned Object is a Boolean or Integer, respectively.
Use these methods if the code is accessing an option of known type. These methods return a boolean value, an int value, and a String object, respectively.
getOptions( )
This method returns a Hashmap object containing all the rendering options that have been set explicitly using setOption( ).
hasOption( )
Use this method to check whether the rendering options object supports a particular option. If the object supports an option, this method returns true even if the value of the option is null.
setOption( )
This method takes a second argument, an Object that contains the value of the option. For boolean or int values, use a Boolean or Integer object, respectively.
The code sample in Listing 5‑12 provides examples of these methods.
Listing 5‑12 Using generic rendering options
RenderOption ro = new RenderOption( );
if ( ro.getOption( RenderOption.RENDER_DPI ) == null ) {
ro.setOption( RenderOption.RENDER_DPI, new Integer( 96 ) );
}
ro.setOption( RenderOption.RTL_FLAG, new Boolean( true ) );
Image directory. Many reports include either static or dynamic images. For example, charts are dynamic images. HTML reports place all these images in a defined location. To set this location, call the setImageDirectory( ) method.