Setting up the rendering options

Before rendering a report to one of the supported output formats, the application must set options that determine features of the output. The options must specify either an output file name or a stream. Other configuration 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 a 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 because this task does not render to an output format. Listing 12‑11 includes code that sets 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 the supported formats, use setSupportedImageFormats( ) with an argument of a String that contains a list of the supported image formats. The image formats are standard types, such as BMP, GIF, JPG, PNG, and SVG. Semicolons separate the items in the list. The method getSupportedImageFormats( ) returns a String of the same format.

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 a web deployment, such as a WAR file for the reporting application, 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 12‑3.

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.