Using the BIRT Web Project Wizard

The EclipseZone editorial team welcomes Virgil Dodson from Actuate with a guest editorial this week. Please be sure to send him some feedback.

Now that you have created your great looking BIRT reports, you need to deploy the design files to make them available to others. There are several different ways to deploy your BIRT report designs. These range from writing all the deployment code from scratch using the Report Engine APIs to writing no code at all with some of the commercial report servers. Somewhere in the middle, there is another option called the Web Viewer Example that will get you off to a nice start. This article will talk about the Web Viewer Example that ships with the Eclipse BIRT Runtime and introduce the BIRT Web Project Wizard that helps you integrate the Web Viewer and BIRT JSP tag library into a web application.

Introduction to BIRT
First, a little bit of information about BIRT. BIRT is a flexible, 100% pure Java reporting tool for building and publishing reports against data sources including databases, XML, Java objects, web services, and more. BIRT stands for Business Intelligence Reporting and Tools and is an Eclipse open source project that benefits from the rich capabilities of the Eclipse platform and a very active community of users. BIRT includes powerful report and chart designers, as well as runtime components for generating and deploying BIRT reports. The BIRT Report Designer provides easy-to-use wizards and point-and-click layout capabilities that are similar to many web page design tools. Finished reports are easily integrated with Java Server Pages, servlets, or existing Java applications and leverage existing application server infrastructure. The rest of this article assumes some level of familiarity with BIRT and will focus on using the BIRT Web Viewer from a BIRT Web Project and using the BIRT JSP tag library.

BIRT Web Project Wizard
To get started using the BIRT Web Project Wizard, you need to be using BIRT 2.2 or higher which can be downloaded here. While in the Eclipse IDE, select File | New | Project, and then select ‘Web Project’ from the ‘Business Intelligence and Report Tools’ section. Press Next and then provide a name for your project and select the Target Runtime for your deployment. I’m selecting Tomcat 5.5 for this example. You can browse and modify the rest of the available settings by selecting Next, or you can accept the defaults by pressing Finish.

Once you are finished, Eclipse will switch to the Java EE perspective so you can work with this type of web project. Locate your project in the Project Explorer and expand the WebContent folder to find index.jsp. Right click on that file and select Run As | Run on Server. Select the server you want to use or define a new server and press Next. Make sure your new BIRT Web Project is listed in the Configured Projects list on the right. Remove any other project that might be in this list and press Next and then press Finish. If everything went as expected, you will see a simple web page (see Figure 1) with a link to a report design example. Select ‘View Example’ to see the report. If you see “Congratulations” then you have successfully run the report.

Figure 1 – Web Viewer Example initial page

Once you have successfully run the example report, you can swap it out with a design of your own. Open index.jsp from the Project Explorer and look for a line near the bottom like the one below:

<a rel="nofollow" href="<%= request.getContextPath( ) + "/frameset?__report=test.rptdesign&sample=my+parameter" %>">View Example</a>

The web viewer is called by using URLs to the frameset servlet mapping and passes parameters specifying which report to run. To run your own report using this method, copy another rptdesign file to your project and replace ‘test.rptdesign’ with the name of your file. Notice that test.rptdesign used a parameter called sample and passed the value of ‘my+parameter’ to the report. Replace that part with your own parameter names and values if desired, or leave the parameters off the URL to use the default values. You can also add ‘__parameterpage=true’ to the URL to force the user to be prompted for the parameters.

If your report depends on external JDBC drivers, you will need to include those prior to running your report. To add your JDBC drivers so the viewer can see them, import your JDBC JAR files into the WEB-INF/platform/plugins/org.eclipse.birt.report.data.oda.jdbc_[version_xxx]/drivers directory. Run index.jsp again and select the View Example URL to run your report. If it was successful, you should see your report.

Figure 2 – Example Report running in the BIRT Web Viewer

BIRT JSP Tag Library
Another option for calling the BIRT Web Viewer from your web project is to use the BIRT JSP Tag Library. There are only 5 base tags (viewer, report, param, parameterPage, and paramDef) and each has several attributes. These JSP tags allow you embed reports or deal with parameters within your JSP page. The rest of this article will show you how to get started with the BIRT JSP tag library and show a few examples of the reports running within a JSP page. I won’t spend much time with the parameter tags as those were explained very well recently in this post from the BIRT World blog.

To get started using the BIRT JSP tag library, right click on WebContent in the BIRT Web Project and select New | Other… Select ‘JSP’ from the ‘Web’ category and then press Next. Provide a name for your JSP page and then press Next. Make sure ‘Use JSP Template’ is selected and then select ‘New JSP File (html,BIRT tag)’ and then press Finish. This JSP Template ensures that the taglib reference below is included.

<%@ taglib uri="/birt.tld" prefix="birt" %>

Once your page is created, you simply need to start typing “<birt…” to see the available tags (See Figure 3).

Figure 3 - BIRT JSP Tag Library

The ‘viewer’ tag allows you to generate and view a BIRT report and includes the Viewer toolbar with the report. The ‘report’ tag is the same as above except it does not include the toolbar. You can see that I used the ‘param’ tag with each to supply the parameter for the report. Output generated is shown in Figure 4. . <birt:viewer id="test1" reportDesign="test.rptdesign" width="600" height="200"> <birt:param name="sample" value="BIRT Rocks!"></birt:param> </birt:viewer>

<birt:report id="test2" reportDesign="test.rptdesign" width="600" height="200"> <birt:param name="sample" value="BIRT Rocks!"></birt:param> </birt:report>

Figure 4 - BIRT JSP Tag Library - 'report' tag and 'viewer' tag examples

If you want to prompt the user for the parameters instead of passing them in, you need to set the ‘showParameterPage’ attribute to ‘true’ like below. This will prompt the user for the parameters and then run the report in the same space allocated by the height and width parameters. (See Figure 5)

<birt:viewer id="test1" reportDesign="test.rptdesign" width="600" height="600" showParameterPage="true"> </birt:viewer>

Figure 5 - BIRT JSP Tag Library - 'viewer' tag using 'showParameterPage' attribute

These steps were intended to get you started with your BIRT Web Project deployment. There is more information available at the URLs below.

References
Official Eclipse BIRT Project Site: http://www.eclipse.org/birt Online BIRT Documentation: http://www.birt-exchange.com/modules/documentation/ BIRT Forums: http://www.birt-exchange.com/modules/forum/

Until Next Time,
Virgil Dodson
VDodson@birt-exchange.com