BIRT Contest

Last week at the BIRT road show in Bangalore, Actuate announced a BIRT contest. The challenge is to extend BIRT by building plug-ins that implement key extension points, like emitters, ODA drivers, charts and report items. The contest runs until October 15, 2011 and the details can be found on the Contest Wiki page.

BIRT Viewer Export Data

When using the AJAX based BIRT Viewer, a user has the option to show the table of contents, re-run the report with different parameters, export report data, export the report to XLS, PDF, PPT, DOC, PS, ODS, ODP, ODT formats, Print from the client, or print on the server. These options are available within the toolbar of the viewer.



The export data function allows the report user to export all the columns in the data binding collection for all data bound items in the report. To see the columns that will show up in the export, select the report item and choose the binding tab in the properties editor.



Within the Export Data dialog, users can configure the output encoding and separator to use when creating the output. Currently the separator supports comma, tab, semi-colon, colon, and vertical line separators.



By default BIRT will use the report element id to generate a name to populate the Available result sets drop down list. This is generally not a user friendly name. If the report designer names the report item in the general properties for a report item, this name will be used instead. In the image above the table is named “mytable”. By default all data bound items will be shown in the drop down list. BIRT provides an advanced property called Allow Export that can be set to true or false. If the value is true for a report item, the report items result set will be shown in the available result sets drop down. If the value is false, the result set will not be shown.




This property can also be set dynamically, using a beforeFactory script and the report elements name.




if( params["ExportChartData"].value == false ){

reportContext.getDesignHandle().findElement("mychart").setProperty("allowExport", false);

}

if( params["ExportTableData"].value == false ){

reportContext.getDesignHandle().findElement("mytable").setProperty("allowExport", false);

}



In this sample two Boolean report parameters are used to determine whether the allow export property should be set to false.



Other conditions can be used to make the decision on whether to display a report item in the available result sets drop down list. For example, from script you could call out to a Java object or access a session variable to make the decision.

The sample report is available at BIRT-Exchange.

BIRT Roadshow heads to India

If you are interested in some free BIRT training, some of the BIRT team will be in Bangalore on August 26th to do a workshop. Ray Gans, the Community Manager for Birt-Exchange.org, has posted the agenda on his blog.

To register for the event, visit the BIRT Roadshow registration site.

BIRT Developer Survey

Feedback from users is one of the key inputs into the BIRT planning process. By filling out this survey, you provide the BIRT team with valuable information on how you use BIRT and how you would like to see it evolve.

Survey should take less than 3 minutes to fill out.
BIRT Developer Survey

Replacing the default BIRT XLS Emitter

If you are using the BIRT 3.7 runtime, the BIRT engine is now in one JAR. See the BIRT 3.7 New and Notable for more details.

While this is optimal for a lot of reasons, it does make it a little more difficult to replace the default BIRT emitters. We have seen this with many users wanting to use the Tribix emitters.

See this thread and this bug for an example of the issues. While replacing the emitter is achievable through the method described in the forum post, it is not very elegant. BIRT supports having two emitters that emit the same output format. When the engine processes a request for a specific output format the first emitter found by the runtime generally processes the request. This may not be desirable. To work around this a user can specify a specific emitter id to process the given output format. So if you have both the Tribix XLS and the default BIRT XLS emitter deployed you can specify which emitter to use to process the report. To illustrate how to do this, we will use the Tribix XLS emitter.

Deploy Tribix Emitter

First download the Tribix emitter and deploy it. If you are using the WebViewer with Version 2.6.2 or earlier, just copy:

org.uguess.birt.report.engine.emitter.xls_version.jar
org.uguess.birt.report.engine.common_version.jar

to the WebViewer/WEB-INF/platform/plugins directory.

If you are using BIRT 3.7 or later extract the following jars from the org.uguess.birt.report.engine.emitter.xls_version.jar.

xl-emitter.jar
lib/poi-3.5..jar
lib/commons-logging-version.jar
lib/commons-jexl-version.jar

Copy these jars to the WebViewer/WEB-INF/lib directory. Make sure they are no longer in the org.uguess.birt.report.engine.emitter.xls_version.jar. Finally, copy the modified org.uguess.birt.report.engine.emitter.xls_version.jar and the org.uguess.birt.report.engine.common_version.jar to the WebViewer/WEB-INF/lib folder.

Specifying Which Emitter To Use

The WebViewer provides a URL parameter, named __emitterid that can be used to specify which emitter to use for the xls format. For example:

This URL will use the default BIRT XLS emitter

http://localhost:8090/WebViewer/frameset?__report=test.rptdesign&sample=my+parameter&__emitterid=org.eclipse.birt.report.engine.emitter.prototype.excel&__asattachment=true&__format=xls

This URL will use the Tribix XLS emitter

http://localhost:8090/WebViewer/frameset?__report=test.rptdesign&sample=my+parameter&__emitterid=org.uguess.birt.report.engine.emitter.xls&__asattachment=true&__format=xls

This does not address the case when you are using the export button in the web viewer. In order to change which XLS emitter is used when the button is pressed, you will need to modify the
BirtExportReportDialog.js file in the WebViewer/ webcontent/birt/ajax/ui/dialog directory. Modify the __exportAction function to add the emitter id parameter to the request.




 __exportAction : function( )
 {
.
.
.
    else
   {
    action = action.replace( reg, "$1=false" );
   }
   if( format=="xls"){
    //action = action + "&__emitterid=org.eclipse.birt.report.engine.emitter.prototype.excel";
    action = action + "&__emitterid=org.uguess.birt.report.engine.emitter.xls"
   }
  
   formObj.action = action;
   formObj.method = "post";   
   formObj.submit( );
   
   return true;
  }




If you are using the Report Engine API, there is a render option available for setting the emitter id.




               EXCELRenderOption options = new EXCELRenderOption();  
               options.setOutputFormat("xls");
               options.setOutputFileName("output/resample/ps.xls");
               options.setOption(IRenderOption.EMITTER_ID, "org.eclipse.birt.report.engine.emitter.prototype.excel");
               IRenderTask task = engine.createRenderTask(document);   
               task.setRenderOption(options);

or



               EXCELRenderOption options = new EXCELRenderOption();  
               options.setOutputFormat("xls");
               options.setOutputFileName("output/resample/ps.xls");
               options.setOption(IRenderOption.EMITTER_ID, "org.uguess.birt.report.engine.emitter.xls");
               IRenderTask task = engine.createRenderTask(document);   
               task.setRenderOption(options);

BIRT 3.7 Released

BIRT 3.7 is now available and with this release many improvements and new features are available. BIRT 3.7 now provides a new POJO based runtime for ease of deployment when using the BIRT Viewer or the Report Engine. Open Document Text (ODT), Open Document Presentation (ODP), and Open Document Spreadsheet (ODS) outputs are also available with the addition of three new emitters. BIRT now provides support for Hadoop through a new Open Data Access Driver (ODA) that allows the developer to build queries using Hive Query Language (HQL) using the designer GUI.



To read more about these and other new features for BIRT, see the BIRT 3.7 New and Notable.

BIRT: Using XLS as a data source

BIRT currently supports many data sources, including XML, Web Services, JDBC and flat files. This list can also be extended by implementing BIRT extension points. Using this method is called implementing an ODA(Open Data Access) extension.

An ODA allows the developer to add custom GUI elements to the BIRT designer to create and manipulate a data source. This method is described in a set of articles located on BIRT-Exchange. BIRT also supplies a scripted data source that allows a developer to write code in a simplified interface to retrieve data using Java or JavaScript. This post explains how a scripted data source can be implemented to retrieve XLS data using the Source Forge Java Excel API project. For more information on using this API see this blog post.

Adding the JAR to the BIRT Project

First download the Java Excel API and extract the jxl.jar file from the download. You can add this Jar to your BIRT project in several different ways. See this post for designer classpath options. One simple way to add the jar is to put the jar in your BIRT Project Resource folder and then add a reference to it in the report design. You can set the resource folder in the BIRT Designer Preferences (Window-Preferences-Report Design-Resource). The resource folder is also a web.xml setting in the deployed viewer.



In the above screen shot we have a resources folder under the BIRT reports project. Just import the jxl.jar into this folder. To create the reference to the jar in a report design, select the properties view for the report and click on resources. Click the add file button in the jar files section of the report resources and add the jar.



The jar file should now be accessible in the designer from script or expressions. When you deploy the report to the Viewer make sure to copy the jar to the resource folder of the deployed Viewer.

If this method of adding the jar is not desirable you can always create a folder in the project containing the lib and add the jar to the project classpath entry (Window-Preferences-Report Design-Classpath). This will allow the jar to be accessed at design time. When deploying the report you can then just copy the jar to the WEB-ONF/lib folder of the deployed viewer.

Implementing the Scripted Data Source/Set

BIRT supports implementing a scripted data source in Java or JavaScript. In this example we implement it using JavaScript. Although the code is written in JavaScript we can still call Java code by using the importPackage method. This example uses this approach.

Use the new data source wizard to add a scripted data source and use the new data set wizard to add a new scripted data set. In this example we are reading a three column xls file, so we define 3 columns in our dataset.





The final portion of this example requires that we add code to the script events to call the Java Excel API. Select the new data set and click on the script tab. From the drop down menu select the open event. Enter the following code.

importPackage( Packages.java.io);
importPackage( Packages.jxl );
try{
 var inputWorkbook = new File(params["XLSLocation"].value);
 myworkbook = Workbook.getWorkbook(inputWorkbook);
 sheet = myworkbook.getSheet(0);
 numrows = sheet.getRows();
 curr = 0;
}catch(e){
 curr=0;
 numrows=0;
}

This code opens an xls file pointed to by the report parameter XLSLocation. You can hard code the file but this example is a bit more dynamic. The code then opens the first sheet in the workbook and sets a global JavaScript variable for the number of rows and initializes a current row counter to zero.



Select the drop down menu and select the fetch event and enter the following code.

if( curr < numrows ){

var cell1 = sheet.getCell(0, curr);
row["col1"] = cell1.getContents();
var cell2 = sheet.getCell(1, curr);
row["col2"] = cell2.getContents();
var cell3 = sheet.getCell(2, curr);
row["col3"] = cell3.getContents();

curr++
return true;
}else{
return false;
}

The fetch event is fired once per row of data and stops processing when the event returns false. In this code we are just retrieving the first three columns of the xls sheet and assigning them to the dataset row columns.



The final event to implement is the close event. Select close from the drop down box and enter the following code.

if( typeof myworkbook != 'undefined'  ){
myworkbook.close();
}

This code closes the workbook.



You should now be able to preview the dataset.



Remember to add the parameter that defines the location of the xls file. Once the dataset is complete you can construct your BIRT report as usual. This attached example produces the following report.



This example is available at BIRT-Exchange.