BIRT Runtime Addition

As part of the 3.7 release BIRT now uses a BIRT POJO runtime. This change was described in the BIRT 3.7 New and Notable. If you are using a version of BIRT prior to 3.7 be sure to check out the Migration Guide. As part of the 3.7.2 release of BIRT which will be released in a couple of weeks, the team has decided to release a second runtime that uses the OSGi runtime. This new download will function similar to the BIRT runtime prior to BIRT 3.7 and is available on the full downloads page. You can try out the 3.7.2 release candidate version of this download by selecting the release candidate on the recent builds page.

BIRT Chart Palette

We have posted many times about the different facets of scripting (client and server side) for BIRT charts. Some of these posts are shown below. In many cases users want to modify chart colors based on some data value or some external logic. While this is very simple with the standard palette colors, some of the other palette options are not as straight forward. In this post we will discuss the different palette options developers have and how to access and modify them from script.

Previous Chart Scripting Posts

Chart Scripting Overview
Using Script to Modify a BIRT Chart
Dynamically Adding a Series to a BIRT Chart
Calling Client Side JavaScript From a BIRT Chart
More on Chart Interactivity

BIRT Palette Options

The BIRT Chart Palette supports standard and custom colors, gradients, images, positive/negative entries and patterns.

While standard and custom colors are simple some of the other types offer some interesting possibilities. The Gradient palette entry allows a start and end color as well as a rotation angle for the gradient.

The Image Palette entry allows a developer to specify a URL or embed an image directly into the chart model.

The Positive/Negative palette entry uses one palette color for positive values and one for negative values.

The Pattern palette entry allows the developer to define a pattern with foreground and background colors. The pattern can be one of the predefined patterns or one that is customized.

Palette Scripting

Many of the events that are triggered during the creation of the chart are passed a fill object. The actual data type of the fill object will depend on how the palette has been setup. The Fill object will be one of the following types:

org.eclipse.birt.chart.model.attribute.impl.ColorDefinitionImpl – Color/Custom Color Palette Entry
org.eclipse.birt.chart.model.attribute.impl.GradientImpl – Gradient Palette Entry
org.eclipse.birt.chart.model.attribute.impl.ImageImpl – Image URL Entry
org.eclipse.birt.chart.model.attribute.impl.EmbeddedImageImpl – Embedded Image Entry
org.eclipse.birt.chart.model.attribute.impl.MultipleFillImpl – Positive/Negative Entry
eclipse.birt.chart.model.attribute.impl.PatternImageImpl – Pattern Entry

For example assume that you have a Bar chart that uses one bar color and you want to change this color based on the Y-Axis value of the data point. The following beforeDrawDataPoint Script could be used.

function beforeDrawDataPoint(dph, fill, icsc)
{
//Fill implements Fill interface 
//ImageImpl
//ColorDefinitionImpl
//GradientImpl
//MultipleFillImpl
//EmbeddedImageImpl
//PatternImageImpl

importPackage( Packages.org.eclipse.birt.chart.model.attribute.impl );
val = dph.getOrthogonalValue();
 if( fill.getClass().isAssignableFrom(ColorDefinitionImpl)){
  if (val < 40){
        fill.set(255, 0, 0);
  }
 }
}

In this particular example the fill object is a ColorDefinitionImpl object that supports setting the R,G,B value of the color. Notice also that we import the org.eclipse.birt.chart.model.attribute.impl package to get access to the ColorDefinitionImpl class. If the palette entry was a gradient the script could be changed to something like the following:

function beforeDrawDataPoint(dph, fill, icsc)
{
//Fill implements Fill interface 
//ImageImpl
//ColorDefinitionImpl
//GradientImpl
//MultipleFillImpl
//EmbeddedImageImpl
//PatternImageImpl

importPackage( Packages.org.eclipse.birt.chart.model.attribute.impl );
val = dph.getOrthogonalValue();
 if( fill.getClass().isAssignableFrom(GradientImpl)){
  if (val < 40){
     fill.getStartColor().set(255,0,0);
  }
 }
}

In this example we set the start color of the gradient.

If you are using a Bubble chart with a Positive/Negative palette entry, by default one color will be used for positive values and the other for negative colors. You could alter this behavior for certain data points. For example the following script changes the positive and negative colors for some of the data points.

function beforeDrawDataPoint(dph, fill, icsc)
{
//Fill implements Fill interface 
//ImageImpl
//ColorDefinitionImpl
//GradientImpl
//MultipleFillImpl
//EmbeddedImageImpl
//PatternImageImpl

importPackage( Packages.org.eclipse.birt.chart.model.attribute.impl );
importPackage( Packages.org.eclipse.birt.chart.extension.datafeed);
//for bubble chart this returns a BubbleEntry 
val = dph.getOrthogonalValue();
yval = val.getValue()
 if( fill.getClass().isAssignableFrom(MultipleFillImpl)){
  if( yval > -500 && yval < 500 ){
   fill.getFills().clear();
   fill.getFills( ).add( ColorDefinitionImpl.BLUE( ) );
   fill.getFills( ).add( ColorDefinitionImpl.WHITE( ) );
  } 
   
 }
}

Notice that we needed to import the datafeed package as the bubble chart has size and value entries for the y-axis. We also used the ColorDefinitionImpl predefined colors for blue and white. We could have created the color using R,G,B values like ColorDefinitionImpl.create( 255, 255, 225 ).

Palette Model Location

While the above examples illustrate how to manipulate palette entries that are passed to the other events, it is often desirable to alter one or more palette entries. This can be done in the beforeGeneration event. How you access the chart palette will depend on what type of chart it is: Chart with Axes or Chart without Axes. For example suppose you want to replace the chart palette with a set of predefined gradients. To do this with a pie chart the following script could be used.

function beforeGeneration( chart, icsc )
{
  importPackage(Packages.org.eclipse.birt.chart.model.attribute.impl);
  sd = chart.getSeriesDefinitions( ).get( 0 );
  sd.getSeriesPalette( ).getEntries( ).clear( );

  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(220,237,248), ColorDefinitionImpl.create(80,166,218), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(255,213,213), ColorDefinitionImpl.create(242,88,106), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(255,247,213), ColorDefinitionImpl.create(232,172,57), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(213,255,213), ColorDefinitionImpl.create(128,255,128), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(213,255,255), ColorDefinitionImpl.create(64,128,128), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(226,226,241), ColorDefinitionImpl.create(128,128,192), 0, false));
   
      
}

In this example we clear the existing palette and replace it with a set of gradients. The palette is attached to the charts first series definition.
For a Bar chart the following script would be used.

function beforeGeneration( chart, icsc )
{
  importPackage(Packages.org.eclipse.birt.chart.model.attribute.impl);

  var xAxis = chart.getAxes().get(0);
  var yAxis = xAxis.getAssociatedAxes().get(0);
  var sd = xAxis.getSeriesDefinitions().get(0);

  sd.getSeriesPalette( ).getEntries( ).clear( );

  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(220,237,248), ColorDefinitionImpl.create(80,166,218), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(255,213,213), ColorDefinitionImpl.create(242,88,106), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(255,247,213), ColorDefinitionImpl.create(232,172,57), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(213,255,213), ColorDefinitionImpl.create(128,255,128), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(213,255,255), ColorDefinitionImpl.create(64,128,128), 0, false));
  sd.getSeriesPalette().getEntries().add( GradientImpl.create( ColorDefinitionImpl.create(226,226,241), ColorDefinitionImpl.create(128,128,192), 0, false));
}

In this example the palette is attached to the series definition associated with the x-axis.
As a more complex example, and afterDataSetFilled script could be used to calculate the number of data points in a particular bar chart. The beforeGeneration event could then use this value to create a palette that gives entire chart a gradient look by moving a start color to an end color.

cnt = 0;
startColor = null;
endColor = null;
importPackage( Packages.org.eclipse.birt.chart.model.attribute.impl );

function afterDataSetFilled(series, dataSet, icsc)
{
 importPackage( Packages.java.io );
 importPackage( Packages.org.eclipse.birt.chart.model.type.impl );

 if( series.getClass() == BarSeriesImpl ){
  if( series.getSeriesIdentifier() == "Series 1" ){
      var list = dataSet.getValues();
      cnt = list.length;
     }
     
 
 }
 startColor = ColorDefinitionImpl.RED(); 
 endColor = ColorDefinitionImpl.ORANGE(); 
}
function buildPalette( mNumber )
{
     var sr = startColor.getRed();
        var sg = startColor.getGreen();
        var sb = startColor.getBlue();

     var er = endColor.getRed();
        var eg = endColor.getGreen();
        var eb = endColor.getBlue();

  var nr = ((er-sr)/cnt)*mNumber + sr;
  var ng = ((eg-sg)/cnt)*mNumber + sg;
  var nb = ((eb-sb)/cnt)*mNumber + sb;        
        
        var nc = ColorDefinitionImpl.create( nr, ng, nb );        
  return nc;


}

function beforeGeneration( chart, icsc )
{
var xAxis = chart.getAxes().get(0);
var yAxis = xAxis.getAssociatedAxes().get(0);
var xSerieDef = xAxis.getSeriesDefinitions().get(0);
var ySerieDef = yAxis.getSeriesDefinitions().get(0);

  xSerieDef.getSeriesPalette().getEntries().clear( );  
  for ( i = 1; i <= cnt; i++ )
  {
   xSerieDef.getSeriesPalette().getEntries().add( buildPalette(i) );
  }
}

The example shown here are available at BIRT Exchange.

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