Wednesday, September 19, 2007

2.2 BIRT Tag Library: Building a Custom Parameter Page

The Web Viewer now contains a tag library that can be used to customize the behavior of the Viewer. This tag library can be deployed by either deploying the viewer as normal or by using the new BIRT Web Deployment project wizard. In addition, if you desire to have BIRT deployed in one context and include the tag library in a separate context this can be done by copying the birt.tld file to your WEB-INF\tlds directory and copying coreapi.jar, modelapi,jar, viewerservlets.jar, engineapi.jar, and com.ibm.icu_3.6.1v20070417.jar from the Viewer libs directory to the new context/web-inf/lib directory. Add the following reference to your web.xml.

<jsp-config>
<taglib>
<taglib-uri>/birt.tld
<taglib-location>/WEB-INF/tlds/birt.tld
</taglib>
</jsp-config>

The following tags are now available:

enlarge

The parameterPage tag can be used to construct your own parameter page before calling the BIRT Viewer. In addition to calling the Viewer several attributes are provided to customize the Viewer appearance and functionality.

For example the following JSP code will present the user with a set of text boxes to enter the two parameters required for the report. The pattern attribute specifies the Servlet mapping to be used and can be set to frameset, run or preview.

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<%@ taglib uri="/birt.tld" prefix="birt" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
</head>
<body>

<birt:parameterPage id="birtParmPage" reportDesign="TopNPercent.rptdesign"
name="my form"
pattern="frameset"
height="600"
width="800"
format="html"
title="My Viewer Tag"
isCustom="true"
showTitle="true"
showToolBar="true"
showNavigationBar="true"
>
TOP COUNT PARAMETER
<input type="Text" name="Top Count">
<br><br>
TOP PERCENT PARAMETER
<input type="Text" name="Top Percentage">
<br><br>
<input type="Submit" value="Run Report">
</birt:parameterPage>
</body>
</html>

If you wish the BIRT Engine to return the HTML it generates for the parameter you can use the paramDef tag in conjunction with the parameterPage tag.

The following code will call the BIRT engine to populate each level of a cascade.

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<%@ taglib uri="/birt.tld" prefix="birt" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
</head>
<style type="text/css">
.class1 { background-color:#ff0000; color: #ffffff; }
</style>
<body>

Parameter Page 1
<br>
<birt:parameterPage
id="report1"
name="page1"
reportDesign="cascade_report.rptdesign"
isCustom="true"
pattern="frameset">

Cascading Parameter1: <birt:paramDef id="5" name="Country" />
<br><br>
Cascading Parameter2: <birt:paramDef id="6" name="City"/>
<br><br>
Cascading Parameter3: <birt:paramDef id="7" name="Customer" cssClass="class1"/>
<br><br>
<input type="submit" name="submit" value="Sumbit form"/>
<br><br>
</birt:parameterPage>
<br>
</body>
</html>


This code will produce the following output. Notice that the third level is also being customized by using a style.

enlarge

Download the 2.2 build and try out the new tag library.