Adding the BIRT Viewer to an RCP Application
The BIRT Viewer is also wrapped as an Eclipse plugin and is located under the eclipse/plugins/org.eclipse.birt.report.viewer_2.1.0 directory within the BIRT Designer install. When BIRT reports are previewed, this is the plugin that is used for generation and viewing. RCP developers can make use of this plugin to embed report generation and viewing capabilities within their applications.
To deploy BIRT in this fashion, first modify your plugin dependencies to include the BIRT viewer, as illustrated in Figure 3.
Figure 3. Dependencies needed to include the BIRT Viewer
The BIRT Viewer depends on several BIRT and Eclipse plugins, such as the Tomcat plugin. For a complete list of required plugins, see the launch configuration (RCP
Example.launch) within the example source code. Also note that additional plugins that are not in the dependency list may be necessary. These are usually determined by the type of report that is being generated and include plugins such as the XML ODA driver, which is used to retrieve data from an XML stream or file.
Next, you will need to add code to your application to run and render the report. BIRT's Viewer plugin makes use of the Eclipse Tomcat plugin to run and render the reports. The BIRT Viewer is a servlet, which runs in the Tomcat plugin. BIRT supplies a utility class, WebViewer, which can be used to launch the application.
The WebViewer class supplies two variants of a method named
display. This method launches the BIRT Viewer, runs, and then renders your report. Both take report name and format as parameters.
public static void display( String report, String format, boolean allowPage )
The first variant of
allowPage as a boolean parameter. If this parameter is
true, the "/frameset" servlet mapping is used. If the parameter is
false, the "/run" servlet mapping is used. As described above, the "/frameset" mapping separates running and rendering of the report, and supports operations such as TOC, Export to CSV, and paginated HTML. The "/run" mapping generates a single HTML page or PDF document with the report output.
display in this manner renders the report in a separate browser window. This may not be desirable. It is possible to render the BIRT reports to an SWT Browser Composite. The second variant of display takes a Browser as a parameter. In the example source, a Browser is added to an Eclipse UI ViewPart, and the report is rendered to this Browser.
public static void display( String report, String format, Browser browser, String servletName )
servletName parameter accepts "run" or "frameset", which allows access to the full capabilities of the BIRT Viewer. The BIRT Viewer allows parameters to be entered. In BIRT 2.1, if your report definition has parameters that are required, and no default value is specified, a parameter entry dialog will be displayed before running the report.
It is also possible to use the
WebViewer.startup method to launch the BIRT Viewer and then use the
Browser.setUrl command to run and render the report. See the source code for an example of this option. Figure 4 shows the result.
//option 1 display with no parameters in url. //Parameter box will display if //required in a separate window. //This uses the /run mapping //WebViewer.display(reportName , // WebViewer.HTML, // false); //option 2 display BIRT Viewer in separate //Browser with /frameset mapping //WebViewer.display(reportName , // WebViewer.HTML, // true); //option 3 display in SWT Browser //using /frameset mapping. //WebViewer.display(reportName, // WebViewer.HTML, // browser, // "frameset"); //option 4 display in SWT Browser // using /run mapping. WebViewer.display(reportName, WebViewer.HTML, browser, "run"); //option 5 display with parameters //encoded in the URL //- Note this required adding //additional functions //Use the TopNPercent.rptdesign //with this example //WebViewer.startup(null); //String format = "html"; //String preParameters = // createURL( "run", reportName, format ); //Make sure to encode your parameters //String parm1NameString = // URLEncoder.encode( "Top Count", "utf-8" ); //String parm1ValueString = // URLEncoder.encode( "5", "utf-8" ); //String parm2NameString = // URLEncoder.encode( "Top Percentage", "utf-8" ); //String parm2ValueString = // URLEncoder.encode( "25", "utf-8" ); //String finalUrl = preParameters + // "&" + parm1NameString + "=" + parm1ValueString; //finalUrl += "&" + parm2NameString //+ "=" + parm2ValueString; //browser.setUrl( finalUrl );
Figure 4. RCP Application with BIRT Viewer embedded