Thursday, January 31, 2008

BIRT Reportlets

BIRT process reports by reading the xml design file (.rptdesign) and optionally producing a binary file called a report document (.rptdocument) and finally renders to one of the supported output formats. One nice aspect of using the report document is that a report can be generated and rendered multiple times at a later date or on a different machine. Running a report this way also allows the user of the engine to optionally render portions of the report document. When using the example web viewer application that comes with BIRT this can be achieved by using the _pagerange and _page URL parameters. For example, if the report document contains a 500 page report you can specify __pagerange=1,5-10 to render only those pages using the /preview servlet mapping.

http://localhost:8080/2.2.1.1/preview?__pagerange=1,5-10&__document=c:/test/myreport.rptdocument&__format=html

or

http://localhost:8080/2.2.1.1/preview?__pagerange=1,5-10&__report=myreport.rptdesign&__document=c:/test/myreport.rptdocument&__format=html&__overwrite=false

Note that if you are using the /frameset servlet mapping with HTML output that this will have no effect. In this particular case you can specify a __page URL parameter and the entire report will be rendered and the specific page will be loaded. The __pagerange parameter will be used with the /frameset mapping, if you select another output such as PDF.

BIRT also supports using bookmarks to locate and render content. Most BIRT report elements support a bookmark expression. The expression can be a simple tag such as “mytable”; or can be complex and based on data retrieved from data sources. The bookmark expression can be set using the BIRT properties view. To render a specific bookmark use the __bookmark URL parameter. When used with the /frameset servlet mapping the viewer will render the entire report and load the page containing the bookmark. When using the bookmark parameter with the /preview mapping the entire report will be rendered and the browser will be scrolled to the proper location. The bookmark parameter can also be used in conjunction with the __isreportlet URL parameter to only render the specific bookmark. When used with /preview mapping only the bookmark will be rendered no matter what output format is rendered. The isreportlet parameter will have no effect if, using the /frameset mapping and rendering to HTML. Rendering to other formats such as PDF will cause the engine to only render the specific bookmark though. As an example assume you have a three page report, where a chart exist on each page. The bookmark expressions for the charts are as follows:

“Chart1”;
“Chart2”;
“Chart3”;

Using the following URL will render only the second chart.
http://localhost:8080/2.2.1.1/preview?__bookmark=chart2&__report=mycharts.rptdesign&__document=c:/test/mycharts.rptdocument&__format=html&__isreportlet=true

Using the following URL will render all three charts and the viewer will load page 2.
http://localhost:8080/2.2.1.1/frameset?__bookmark=chart2&__report=mycharts.rptdesign&__document=c:/test/mycharts.rptdocument&__format=html&__isreportlet=true

If you are using the Report Engine API, these results can be achieved using methods of the RenderTask.

IRenderTask task = engine.createRenderTask(myreportdocument);

task.setPageRange("1-3");
or
task.setPageNumber(3);
or
task.setReportlet("chart3");