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);