BIRT World

BIRT Runtime Addition

2012-01-27T07:54:00.000-08:00

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

2011-10-26T11:18:00.000-07:00

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

2011-08-30T07:49:00.000-07:00

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

2011-08-26T10:49:00.001-07:00

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

2011-07-29T09:55:00.000-07:00

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

2011-07-26T14:09:00.000-07:00

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

2011-07-21T10:27:00.000-07:00

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


               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

2011-06-21T21:11:00.001-07:00

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

2011-05-24T10:16:00.000-07:00

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.

BIRT - Reducing large queries and custom navigation controls

2011-04-28T10:23:00.000-07:00

Often times when writing a report that requires large amounts of data, the query times become burdensome. This will lead to dissatisfaction from customers of your report. To get around this issue certain companies like Actuate implement progressive viewing in their products that start returning formatted data before the report generation process is complete. This allows users of the report to start getting data long before the total report is completed.

Another option is to reduce the large queries into smaller queries and add navigation controls to your report to get the next smaller set of data. For example, if you have a customer listing report, the first query may return all customers whose name starts with the letter A. A set of navigation controls could have a next button that returns customers whose name starts with the letter B, etc. This approach is very simple in BIRT and this post details one way of doing it.

As an example we can use the classic models sample database that comes with BIRT. It contains a customers table. To return all customers starting with A we could use the query select * from customers where customername like ‘A%’. We want the report to be dynamic, so we will need script to modify the query on the fly. We can begin by just adding a new datasource that uses the classic models database. Next we create a dataset with the following query:

Select * from customers

The next step is to add a hidden report parameter that we use in script to add a where clause to the query. In this example the parameter is named “like”.

The parameter is hidden and has a default value of A. We can now use this parameter in the beforeOpen script of the data set we created earlier. This script should look like the following:

this.queryText = this.queryText + " where customername like '" + params["like"].value + "%'";

This script will change the query every time the report runs and will append the where clause with the hidden report parameter. The default value for the parameter is A which should list all customers starting with A. Before adding navigation controls to the report we need to create and calculate some global variables that our controls will need. Ideally we will add a previous and a next button to the report. In addition it would also be nice to have a list A-Z that the user could click on to go directly to a set of customers. So at the minimum when the report runs we need to get the parameter for the report and calculate what the previous and next customer names should start with. For example if the parameter is C, previous should be B and next should be D. This can be done with a simple beforeFactory script like:



switch( params['like'].value ){
case 'A':
prev='Z';
next='B';
break;

case 'B':
prev='A';
next='C';
break;

case 'C':
prev='B';
next='D';
break;
.
.
.
}

The beforeFactory script is used because it runs before data is retrieved and executes only once. The BIRT initialize script can be executed multiple times so it is not ideal for this script. The var keyword is also not used with the variables prev and next which will make them visible to downstream events. You could also use the reportContext.setGlobalVariable method to do store the variables as well.

After the table is added to the report you can then add a Text element that contains a script tag to implement your prev and next buttons.

Remember to set the type to HTML. The script tag contains a client side script that just reloads the report with a new value for the like parameter. This function is called nextData and takes the new like value as a parameter. The text element also contains two buttons that call the nextData function with the prev and next server side javascript variables we calculated in the beforeFactory. Notice this is done with the VALUE-OF tag. This tag allows us to combine server side scripting with client side scripting.



<script>
function nextData( a ){
var cl = new String(location.href);
var targetURL = new String();
var tst = cl.indexOf("&like");
if(  tst == -1 ){
 cl = cl + "&like=" + a;
}else{
 var ch = cl.indexOf("&like=");
 cl = cl.substring(0, ch) + "&like=" + a;
    
}
window.location = cl;
}
</script>
<input type="button" value="Previous"
onclick="nextData('<VALUE-OF>prev;</VALUE-OF>')" >
<input type="button" value="Next"
onclick="nextData('<VALUE-OF>next;</VALUE-OF>')" >

The last thing we add to the Text element is an Alpha index for all letters of the alphabet.



<br>
<a href="#" onclick="nextData('A');return false">A</href>
<a href="#" onclick="nextData('B');return false">B</href>
<a href="#" onclick="nextData('C');return false">C</href>
<a href="#" onclick="nextData('D');return false">D</href>
<a href="#" onclick="nextData('E');return false">E</href>
.
.

This allows the user to directly select a letter to use in the like clause. The output for the report looks like the following.

The report also handles the situation when no data is returned.

The no data label is placed in a grid below the table. The grid is bound to the table so it uses the same dataset. The dataset contains an aggregate computed column that counts the number of rows. This computed column is then used in the grid and the table visibility property.

For example the grid visibility is shown below.

The expression is:
(row["myrowcount"] > 0)
The expression returns true when rows exist. This will then hide the grid and label. The opposite condition is used on the table.
(row["myrowcount"] < 1)
This report is available at Birt-Exchange.

BIRT Roadshow coming to a city near you.

2011-03-30T14:11:00.000-07:00

Actuate is continuing the very popular BIRT Road Shows that feature a free day of training on BIRT technologies. If you are interested, the dates and cities for April and May are listed below. Slots fill up fast so be sure to register quickly. More information is available here.

April
Seattle, WA Tuesday | 4/5
Minneapolis, MN Wednesday | 4/6
Indianapolis, IN Thursday | 4/7
Philadelphia, PA Wednesday | 4/13
May
Denver, CO Tuesday | 5/3
Toronto, ON Wednesday | 5/4
Princeton, NJ Tuesday | 5/10
Orlando, FL Wednesday | 5/11
Dallas, TX Thursday | 5/12
London, UK Thursday | 5/19
Louisville, KY Tuesday | 5/24
Washington, DC Wednesday | 5/25

BIRT 2.6.2 Enhancements

2011-03-04T10:25:00.000-08:00

BIRT 2.6.2 is now available and is a maintenance release with a primary concern on bug fixes. This generally means not many new features are introduced. That said a couple of bug fixes merit special attention. The full list of available fixes can be found here.

BIRT Pagination and Page Scripts

BIRT 2.5 introduced page variables and page scripts. These features added the ability to repaginate based on things like a group change. So in one report output you could add a page variable that showed the page count and current group page number within a group. The full details for this feature are available in the BIRT 2.5 new and notable.

While using this feature is very nice, a particular bug caused the scripts not to fire when using a page break interval of 0. The page break interval is one of the many ways in BIRT to introduce a page break in the output. It essentially informs the engine to process a certain number of rows and then insert a page break. If the interval for a table is set to 0, the engine inserts page breaks when all the master page available real-estate is used. In BIRT 2.6.2 this bug is now fixed, allowing the designer to enter a page break interval of 0 in conjunction with page scripts.

The above example can be downloaded from BIRT-Exchange.

To see some of the pagination bugs that were addressed in 2.6.2 see this bugzilla query.

URL security bug

A security issue with the example Web Viewer was identified which posed a cross-site scripting vulnerability. The issue has to do with the __report URL parameter. This parameter specifies the report for the viewer to run. In previous versions of BIRT a fully qualified URL could be used to specify the report, which allowed the report to reside on a completely different server. Since BIRT reports can contain JavaScript which runs server side this poses a scripting risk. The full details for the bug are located here.

BIRT 2.6.2 fixes this issue by adding a web.xml entry that allows the developer to control what value can be used in the __report URL parameter. The entry is named URL_REPORT_PATH_POLICY and has three valid values (all, domain, and none). If the all value is specified no checks on the URL parameter are performed. This value should only be used when access to the viewer is restricted to a known user base. When the none option is used, only local reports to the viewer context for the server are allowed. When the domain option is used the report can contain a fully qualified URL as long as the domain for the server is the same.

If you cannot upgrade the viewer, the patch details are available in the bugzilla entry.

Formatter object

BIRT 2.6.2 now offers a formatter object in the expression builder to format dates, strings and numbers within a given expression. This function is detailed in the following post.

Radar Chart

The Radar Chart in BIRT was implemented in BIRT 2.6 to function as an example on how to implement your own chart types. The source for this chart type is available in two of the BIRT plug-ins (org.eclipse.birt.chart.examples and org.eclipse.birt.chart.examples.core). In BIRT 2.6.2 this chart type has been improved and it now supports rendering multiple series on the same radial within a radar chart.

The GUI for building the radar chart has also been improved to support a more optimal layout for configuring portions of the chart.

BIRT Formatting numbers and dates

2011-02-18T12:46:00.000-08:00

BIRT offers many options when formatting data is required. This post discusses some of the common ways this can be done using the GUI, script and expressions.

Using the GUI to format data

When formatting the standard Data report item, customizing the format is very simple. Located within the properties view for the data item are three tabs that allow formatting a number, date, or string. Which format the data item uses will depend on the data type for the data item as specified in the binding.

Each of the format tabs provides a set of predefined patterns that can be applied to the data. In addition, the pattern can be set to custom allowing the developer to define very specific formatting codes. The formatting operation can be set to a specific locale or auto which will use the locale of the user running the report. For example, entering ¤###,##0.00 as the pattern for a data item that is going to contain a currency may produce €131,44 for the French locale, and $131.44 for a US locale. For an example of using positive:negative patterns you may want to have a look at this post.

Report parameters selections can also be formatted in similar fashion to a Data report item. Each parameter has a “Format As” selection within the Parameter Editor. By selecting the change button a standard or custom format can be applied to parameter.

Formatting labels within the chart builder is also possible. Most items in a chart that display data have an associated format that can be customized by using the format button. For example to format a date axis use the GUI as presented below.

Formatting Data using the Expression builder or Script

The above formatting solutions work very well, but there are times when you want to mix formatted data within a string. In this case you can write script, use and expression, or use a Text report item to format the data. For example assume a report has two dates that are passed as parameters and you want to generate text within the report that shows “Start Date – End Date”. This is not achievable using the GUI methods described above. To do this you can use a text item and the value of syntax:



Start Date: <VALUE-OF format="MMM-dd-yy">params["date1"].value;</VALUE-OF>
End Date: <VALUE-OF format="MMM-dd-yy">params["date2"].value;</VALUE-OF>

In this example the VALUE-OF syntax is evaluated at runtime of the report and the format attribute is applied to the output. This approach also works with numbers. For example, <VALUE-OF format="$#,##0.00">row[“MyData”];</VALUE-OF>.

This same functionality could have been achieved by using a data item with the following expression.



var mydt1 =params["date1"].value
var mydt2 =params["date2"].value

importPackage( Packages.java.text );
var sdf = new SimpleDateFormat("MMM d, yyyy", reportContext.getLocale());
var mydtf1 = sdf.format( mydt1 );
var mydtf2 = sdf.format( mydt2 );
"Start Date: " + mydtf1 + " End Date:" + mydtf2

In this example we are just using the imported Java SimpleDateFormat class to do the formatting.

If you are using BIRT 2.6.2 or higher, you can use the Formatter function within the expression builder to format localized numbers, dates and string as well. The Formatter function is available within the BIRT Functions Category of the expression builder. To build the example above, use the following expression in data item.



var mydtf1 = Formatter.format( params["date1"].value,  "MMM d, yyyy");
var mydtf2 = Formatter.format( params["date2"].value,  "MMM d, yyyy");
"Start Date: "+mydtf1 + " End Date " + mydtf2 + BirtDateTime.diffDay(params["date2"], params["date1"]) +" Days";

In this example we have combined the start and end dates with the BirtDateTime.diffDay function to build a string that not only shows the start and end date, but shows the duration of days.

The Formatter function takes the current locale into account when formatting the element. If you want to test different locales, either set the preview locale in the preferences or use the __locale parameter in your report URL.

As a side note, if you are interested in adding your own functions to the expression builder, see this post.

You can also import Java classes to manipulate data points within the BIRT or Chart event handlers. For example to set your own format on an axis label the following script could be used on a chart.



function beforeDrawAxisLabel( axis, label, context )
{
 importPackage(Packages.org.eclipse.birt.chart.model.attribute);
 importPackage(Packages.java.lang);
 importPackage(Packages.java.text);
 if( context.getExternalContext().getScriptable().getParameterValue("MyParameter") == "date"){
  if (axis.getType() == AxisType.TEXT_LITERAL)
  {
   value = label.getCaption().getValue();
   var dtf = new SimpleDateFormat("MM/dd/yy");
   var dt = new Date(value);
   var fn = dtf.format(dt);
   label.getCaption().setValue(fn); 
  }
 }

As another example, the code below could be placed in a report parameter’s getDefaultValueList event handler to return the current year.



importPackage( Packages.java.util );
cal = Calendar.getInstance(); 
tyear = cal.get(Calendar.YEAR); 
tyear;

Changing Eclipse BIRT Indigo Version Number to BIRT 3.7

2011-01-27T08:52:00.000-08:00

For the BIRT project’s Indigo release in June of this year, our plan continues to be to match the BIRT version number with the Eclipse Platform version number used for Indigo. Going forward, this will make it easier for everyone to remember which version of BIRT is designed to work with which version of the Platform. And with Indigo being the 8th major release of the BIRT project, there is no downside with updating the release number to match the Platform release.

At the outset of the Indigo project, it was an open question whether Indigo would be Eclipse 3.7 or 4.0 – so as a short term measure, we adopted BIRT 4.0 as the working release number for BIRT Indigo. Now that the Indigo release will be designated Eclipse 3.7, we plan to update BIRT Indigo to use the BIRT 3.7 designation.

Building BIRT Based Dashboards

2011-01-14T07:35:00.000-08:00

If you are using Actuate’s iServer technology, one of the new features for version 11 is the ability to build dashboards using nothing but the browser. These dashboards can be constructed using open source BIRT reports, portions of a BIRT report, Flash Objects, Google Gadgets, and other web content. Completed dashboards and gadgets can be shared with others and can be included in other web applications using the Actuate JSAPI.

To start building a dashboard, select the new tab icon in the Actuate Information Console.

This will create a dashboard canvas as shown below.

By selecting the down arrow icon on the newly created tab, you can share the dashboard, rename it, set the layout or define data that will be used in the dashboard. Using the Options field will also allow you to set the refresh time for a dashboard. This can be used to present things like live charts or tables. The layout option allows you to define how the dashboard is presented. You can set a columnar option or freeform which allows you to place the gadgets anywhere on the canvas.

The Dashboard and Gadget Gallery menu items contain previously constructed items that have been shared. The New Gadget menu contains the Gadgets that can be placed on the canvas. There are four categories depending on what type of gadget you wish to use: Data Visualization, Data Selection, Report and Extras.

Data Visualization Gadgets

The Data Visualization category contains a set of gadgets that can be used to analyze data. These include a crosstab, a table, and a set of Flash charts.

To use one of these gadgets, simply drag it to the canvas below the menu. For example, dragging the crosstab gadget onto the canvas will launch the Crosstab Builder.

The gadget retrieves its data from a data object or from an on-demand data design. The data design is essentially a set of BIRT data sources, data sets and data cubes. This allows you to leverage existing open source BIRT Reports as content for your dashboard. After assigning the design values for the crosstab you can move the gadget around the canvas to a suitable location.

Placing one of the chart types will launch the Chart Builder, which allows specifying the chart data.

Most data visualization gadgets support further customization for filtering and formatting. In addition the data can be further analyzed by drilling into the data by clicking on actionable fields or by using the Actuate Data Analyzer.

Data Selection Gadgets

The Data Selection category contains a set of gadgets that present selection able data that can be used to drive other gadgets. These gadgets include items like lists, combo boxes and calendar selectors. To use these, just drag the gadget to the canvas and set the data similar to process used for Data Visualization gadgets.

Once the gadget is placed you can link it to another gadget by selecting the target gadget and clicking on down arrow in the upper right corner of the gadget and select link.

This will launch the link editor where you can set field in the target you wish to link on.

In this particular example the selector updates the report parameter OrderDate for the Report Gadget. Once the linking is complete any time the selector is updated the target gadget will get updated with the new value. Selectors can be linked to multiple gadgets. For example, in the following screenshot, the product line list selector updates an exploded pie chart and a detail report.

Report Gadgets

The Report category contains a set of gadgets that handle presenting BIRT report content. This can include BIRT designs or generated documents, which allows for a cached or on demand design paradigm. In addition the design or document can be further processed to only display a given object in a report or document. Finally a parameter gadget allows the user to use a gadget that displays the parameters for a particular report. This gadget can then be linked to a report gadget, which will be updated when the parameter gadget is changed.

When dragging these gadgets to the canvas a New Report Gadget dialog will be displayed, this allows you to configure the location and parameters for a given report.

Using the refresh timer on the dashboard will also allow you to update how often the report is updated.

The Reportlet gadget allows the user to define a portion of a BIRT report or document to display. When using these one extra field is available in the New Report Gadget dialog. The field is the Bookmark field and corresponds with bookmark property for the report item in the BIRT report design.

In this example the bookmark Hist is located in the MasterSalesDashboard report design. The Hist bookmark in the BIRT report design corresponds to a grid report item that contains historic sales data.

The Parameter gadget functions similarly to the Report and Reportlet gadgets, but only displays the parameter entry dialogs. Once you have a Parameter gadget and a Report gadget on the same canvas you can link them by editing the Report gadget using the down arrow in the upper right corner of the gadget.

In the Edit Report Gadget dialog choose the Parameter Display Setting tab and in the first drop down select Link to Selectors. For each report parameter use the succeeding drop down menus to link them to the parameter gadget.

Once this is complete updating the parameter in the Parameter gadget will update the report in the Report gadget.

Extras Gadgets

The Extras category contains a set of gadgets that allow you to include images, HTML, customized text, video and Google gadgets in the dashboard.

Each gadget will have a custom dialog for configuring the gadget. For example the Import Gadget item dialog allows you to specify the location for a Google Gadget.

Conclusion

This post is an overview of the building BIRT based dashboards using Actuate technology. If you want more details see the help documentation. If you want to try out this functionality download it from BIRT-Exchange.

BIRT Background/Watermark Images

2010-12-02T13:03:00.000-08:00

Back in September I wrote a post about the BIRT Image report item. In that post I did not say much about creating background or watermarks for BIRT reports. In this post I will cover a few ways this can be accomplished.

One of the simplest approaches is to just add your watermark/background image to the resource folder that you have configured in the designer. Note that you will also need to add the image to the resource folder of the deployed environment. Once you have the image in the resource folder, select the style icon in the outline view and create a new style. Set the background image for the new style to the image you added to the resource folder. Next select the master page tab in the report editor and then right click on the canvas background and apply the new style.

The watermark can also be made to be dynamic. For example assume you want one watermark for pdf output and one for html. To do this you could add the second watermark to your resource folder and then use the following beforeFactory script to swap the image.



if( reportContext.getHttpServletRequest().getParameter("__format") == "pdf" ){
reportContext.getDesignHandle().findStyle("BackgroundStyle").backgroundImage = "watermarkpdf.png";
}else{
reportContext.getDesignHandle().findStyle("BackgroundStyle").backgroundImage = "watermarkhtml.png";
}

There is one drawback when using this approach. Master page content is always created in the generation phase of the BIRT pipeline, which means if you use the BIRT Viewer and export the report to another format the above code will not work. This is because the frameset mapping in the Viewer generates an rptdocument that can be rendered in additional formats without the need to re-execute the report. If the report is not re-executed the master page background image cannot be changed.

Another option which will facilitate exporting the report is to use a grid item instead of the master page for the watermark. For example assume there is one table in the report design. You can add a grid to the report that has one column and one cell. Set the height for the grid to be the size of your page (eg 11 in). Drag the table into the cell. Select the grid row and apply your background style.

Using the following onRender script of the grid row will allow you to change the style image at render time.



if( reportContext.getHttpServletRequest().getParameter("__format") == "pdf" ){
this.getStyle().backgroundImage = "watermarkpdf.png";
}

The examples used in this post are available on Birt-Exchange.

Last Day For EclipseCon Submissions

2010-11-29T20:35:00.000-08:00

Tuesday is the last day for EclipseCon submissions. This is a great time for all of you to share your experiences working with BIRT.

BIRT Duplicate Rows

2010-10-21T12:45:00.001-07:00

Currently BIRT supports suppressing duplicate columns values. To do this you can select the table column and in the general properties click the Suppress duplicates checkbox.

This will have an effect similar to the following image.

You will notice that the number of rows generated in the table has not changed, but no order number is repeated. If your table does contain duplicate rows, meaning each column in the table has the same data as the row before and you suppress duplicates on each column, the number of rows displayed by BIRT will be reduced. For example assume your table is tied to a dataset that has two columns and every row contains the same data.

If this dataset is bound to a table and both columns are set to suppress duplicates the following will be displayed.

The actual number of rows is not reduced but the table only shows the value for one row. In the generated HTML a TR element is created for each empty row with empty values. If you use this approach make sure to set the padding on the table row, cell, and data items to 0 or you will get unwanted space for empty rows. It is also important to realize that these empty rows are counted if you are use the page break interval property to handle page breaks. As a side note, when dealing with duplicate rows it is often better to allow the database to handle culling repeated rows, but in some cases like flat file data sources this may not be an option.

Another option that can be used to hide duplicate rows is scripting and a visibility expression.

Assume we have a table that shows order numbers. If we only want a particular order number to be shown once, we obviously could use a distinct on the query. If that is not an option you can use a script and a visibility expression to implement this requirement. On the table row’s onCreate method you could enter a script like:



var rowLast = this.getRowData().getColumnValue("ORDERNUMBER");
reportContext.setGlobalVariable("rl", rowLast);

And a visibility expression like:



if( row["ORDERNUMBER"] == reportContext.getGlobalVariable("rl") ){
true;
}else{
false;
}

This will cause the BIRT engine to only show the row if its current row order number is different from the previous row.

As with the previous examples and all visibility operations the underlying data is not altered. It is just not displayed. For example if you hide a table the dataset still executes. If you want to alter the underlying data you will need to filter the data either on the table or the actual dataset. This can be difficult when trying to get a rows previous value so I created a simple aggregate extension Plugin that will do this for you. It is based on Scott’s post on Optimistic sums. The extension point has been revised slightly since that post so take a look at the attached examples to see the source code. The extension point adds a previous value aggregate function to BIRT. To use it you can create a computed column on the dataset.

The function stores the last row value as entered in the Column expression. Once the computed column is added to the dataset you can then select the filters tab and enter a filter like:

This will filter the dataset as shown below.

The source for this post is available at Birt-Exchange. The download contains two reports (one that uses the aggregate function and one that was demonstrated earlier in the post), the exported new aggregate plugin, and a source project for the plugin.

BIRT Java Object Data Type

2010-10-15T10:39:00.000-07:00

In addition to simple data types BIRT also supports a Java Object Data type. This type can be useful when writing reports that use scripted data sources that consume POJOs that contain a member object. For example assume you have an array of objects and each of these objects contains three member variables (a String, an Integer, and an Object).

Before BIRT supported the Java Object data type you could write a scripted data source that iterated the array and assigned a row variable for the string member and another for the integer variable. If you wanted to use the Object member you would need to call some method on the object that returned a BIRT primitive type. While this is generally not a drawback with a simple table, if you wanted to nest tables and use the inner object in another dataset, scripting this became very complex. Using the Java Object data type now makes this much easier. The only caveat to using the Java Object data type is that the object must be serializable. The reason for this is that BIRT caches datasets and the object will be cached just like any other column value.

To illustrate using the Java Object type, consider the following classes. The BIRTOuterJavaObject contains string, integer, and object member variables.



package test.birt.javaobject;

import java.io.Serializable;

public class BIRTOuterJavaObject implements Serializable {


 private static final long serialVersionUID = 6530113212317618087L;
 private String outerstring;
 private int outerint;
 private BIRTInnerJavaObject innerobj;

 public String getOuterstring() {
  return outerstring;
 }

 public void setOuterstring(String outerstring) {
  this.outerstring = outerstring;
 }

 public int getOuterint() {
  return outerint;
 }

 public void setOuterint(int outerint) {
  this.outerint = outerint;
 }

 public BIRTInnerJavaObject getInnerobj() {
  return innerobj;
 }

 public void setInnerobj(BIRTInnerJavaObject innerobj) {
  this.innerobj = innerobj;
 }

 public BIRTOuterJavaObject() {

 }
}

The BIRTInnerJavaObject is just a sample object that stores information about an automobile. It contains three member variables which are all strings.



package test.birt.javaobject;

import java.io.Serializable;

public class BIRTInnerJavaObject implements Serializable {

 private static final long serialVersionUID = -4509250036928470517L;


 private String make;
 private String model;
 private String year;
 public String getMake() {
  return make;
 }
 public void setMake(String make) {
  this.make = make;
 }
 public String getModel() {
  return model;
 }
 public void setModel(String model) {
  this.model = model;
 }
 public String getYear() {
  return year;
 }
 public void setYear(String year) {
  this.year = year;
 }
 public BIRTInnerJavaObject() {
 this.year = "2009";
 this.make = "Chevrolet";
 this.model = "Corvette";
 }
 public String toString(){
  return "Make:--"+this.make+" Model:--"+this.model+" Year:--"+this.year;
 }
}

The BIRTRow class sets up the array of objects that will be used in the report.



package test.birt.javaobject;

import java.util.ArrayList;

public class BIRTRow {
 
 private ArrayList rows = null;
 
 public BIRTRow() {
  rows = new ArrayList();
  rows.clear();
 }
 public void setupRows(){
  
  BIRTOuterJavaObject row1o = new BIRTOuterJavaObject();
  BIRTOuterJavaObject row2o = new BIRTOuterJavaObject();
  BIRTOuterJavaObject row3o = new BIRTOuterJavaObject();
  
  BIRTInnerJavaObject row1i = new BIRTInnerJavaObject();
  BIRTInnerJavaObject row2i = new BIRTInnerJavaObject();
  BIRTInnerJavaObject row3i = new BIRTInnerJavaObject();
  
  
  row1i.setMake("Toyota");
  row1i.setModel("Land Cuiser");
  row1i.setYear("2008");
  row1o.setOuterint(1);
  row1o.setOuterstring("Outer Row 1 String");
  row1o.setInnerobj(row1i);
  rows.add(row1o);
  
  row2i.setMake("Jeep");
  row2i.setModel("Cherokee");
  row2i.setYear("2002");
  row2o.setOuterint(2);
  row2o.setOuterstring("Outer Row 2 String");
  row2o.setInnerobj(row2i);
  rows.add(row2o);
  
  row3i.setMake("Land Rover");
  row3i.setModel("LR3");
  row3i.setYear("2006");
  row3o.setOuterint(3);
  row3o.setOuterstring("Outer Row 3 String");
  row3o.setInnerobj(row3i);
  rows.add(row3o);
  
 }
 public ArrayList getRows(){
  return rows;
 }
}

The primary goal of the example is to nest two tables. The outer table will have three columns. One column for each of the member variables of the outer object(BIRTOuterJavaObject). The Inner BIRT table will contain three columns as well, one for each of the member variables of the inner object(BIRTInnerJavaObject). Note that in this example the inner object could have contained a list of objects but for simplicity it only contains one object. Because the inner dataset will only return one row of data the example could have been completed using just one data set. So the report will contain two datasets one for the outer object and one for the inner object. The inner object dataset will be parameterized so that when we nest the inner table it can get the object from the outer dataset. The inner dataset will only return one row of data.

The outer dataset scripted data set code is as follows:
Open Method:



importPackage(Packages.test.birt.javaobject);
myrows = new BIRTRow();
myrows.setupRows();
rowsiter = myrows.getRows().iterator();
icnt = 0;

The open method sets up the array of objects and gets an iterator for the list.
Fetch Method:



if( rowsiter.hasNext() )
{
var obj = rowsiter.next();
row["OuterString"] = obj.getOuterstring();
row["OuterInt"] = obj.getOuterint();
row["InnerObj"] = obj.getInnerobj();
icnt++;
return true;
} else {
return false;
}

The fetch method iterates over each of the outer objects and assigns the column values. Note that the InnerObj column is of type Java Object and will be an instance of BIRTInnerJavaObject.

The inner dataset has three string columns.

The inner dataset also has a parameter that we will set when the table is nested. The parameter is named JavaObjectParam and its default value is set to null.

The inner data set code is as follows:

Open method:



importPackage(Packages.test.birt.javaobject);
if( inputParams["JavaObjectParam"] == null ){
icnt=1;
}else{
icnt=0;
}

The open method just checks to see if the dataset parameter is set. If the parameter is null the dataset will not return any rows. If the parameter is set the dataset will only return one row which is an instance of BIRTInnerJavaObject.

Fetch Method:



if( icnt > 0 )return false
var obj = inputParams["JavaObjectParam"];
row["Make"] = obj.getMake();
row["Model"] = obj.getModel();
row["Year"] = obj.getYear();
icnt++;
return true;

In the fetch method we get the object from the parameter and call the getter methods for the object and assign them to the column values.

Once both datasets are created, you can drag the outer dataset to the report canvas which will create the first table. Next add a column to the first table and drag the second dataset to the new column which should create the second (nested) table. To make the inner table work properly the dataset parameter has to be bound to the outer tables InnerObj column. To do this select the inner table and click the binding tab in the properties view. Click the data set parameter binding button and set the value of the dataset parameter to row[“InnerObj”].

The Java Object Data type can also be consumed by a chart. Continuing with this example if you add a chart and bind it to the outer dataset you can specify getter methods for the series, categories, optional grouping, tooltip help, etc.

The completed report should have similar output to the following.

This example is available at BIRT-Exchange as two projects. One Java project and one BIRT Report project. To run the example import both projects to your workspace, open the BirtJavaObjectReport.rptdesign and preview the report.

If you are using Actuate BIRT 11, The Java Object data type can be used in conjunction with the new POJO ODA data source that allows the Report Designer to access and report off of POJO’s using a GUI designer. If you are interested in this approach take a look at this blog post and this video that show the driver in action. An example of using this new data source is available on BIRT-Exchange and you can try out Acutate BIRT 11 by downloading it here.

Format Negative Numbers

2010-09-22T13:57:00.000-07:00

Just a simple little tip this week. I wanted to format numeric data with a custom format. I wanted positive numbers to look like this relatively standard format

1,233.00

But I also wanted negative numbers to show up like:

1,245.00 -

With the negative sign showing to the right of the number.

At first this was a this is a bit of a problem. I figured out a way to do it using OnRender script, but it was kind of ugly. Turns out the solution is quite a bit more simple. BIRT is using the java DecimalFormat for numeric data in the CustomFormat. One of the accepted patterns for DecimalFormat is in the form of

PositivePattern ; NegativePattern

So all you need to do is select Custom Format and enter the format as (see below)

 #,##0.00; #,###.00 -

Open Source Reporting Comparison - BIRT vs. Pentaho vs. Jasper

2010-09-13T18:20:00.000-07:00

This is a post by Scott Rosenbaum of Innovent Solutions. It does not necessarily reflect the view of any of the other BIRT project members.

One of the things that I often get asked is how does BIRT compare to BrandX? For the last six years, I have been creating solutions using BIRT, so the easy answer would be just use BIRT. Unfortunately it is not that simple.
Innovent Solutions' corporate goal is Enabling Intelligent Decisions^® and we use a variety of commercial and open source tools to achieve that goal. Over the last fifteen years, experience has taught us:

Analysis, communication, and project management are the keys to BI and reporting success
Any sufficiently mature technology can be successful in the right situation

So how does BIRT compare to BrandX? requires a bit more than just use BIRT. Most of the answer depends on the business issue that we are trying to solve. But we also have to evaluate if BrandX has reached the point of being sufficiently mature.

Over the last three years three open source business intelligence and reporting projects have emerged as leaders. BIRT, JasperReports, and Pentaho dominate the open source business intelligence and reporting space. In my opinion, BIRT reached the minimum maturity level with its 2.2 release in 2007, since then the product has continued to mature through three annual releases (2.3, 2.5, 2.6).

So what about Jasper and Pentaho, how do their features compare to BIRT, and are they sufficiently mature? In an effort to come up with a better answer, Innovent Solutions has conducted a product comparison of the open source report development tools from each project.

The full evaluation is available on the the Innovent Solutions web site (free, no registration). The starting point for the product comparison can be found at Product Comparison Overview. If you are interested in specific comparisons, we have one for BIRT versus Jasper and another for BIRT versus Pentaho. We also created a side by side feature comparison the Open Source Comparison Matrix (BIRT, Jasper, Pentaho).

NOTE: I would love to hear what you think of the Innovent comparison, but I would like to keep the focus of this blog on BIRT. For this reason I have turned off comments for this post. Comments about the comparison should be made from the Product Comparison Overiew page on the Innovent Solutions web site.

Beyond BIRT Basics - Roadshow

2010-09-08T09:31:00.000-07:00

The advanced BIRT Roadshows will begin next week in Boston, New York and DC.
These events feature a free day of training on advanced BIRT topics, like understanding the event model, chart and report item scripting, implementing high performance reports, and making BIRT mobile.

The schedule for the month of September is listed below.

Upcoming Accelerated BIRT Roadshows
Boston – Tuesday, September 14
New York – Wednesday, September 15
DC – Thursday, September 16
Bay Area – Tuesday, September 28

If you are interested, sign up quickly, as space is limited.

BIRT Image - Report Item

2010-09-02T07:10:00.000-07:00

BIRT has many ways to include images within a report. Images can be used in BIRT styles, as watermarks, in text elements, and placed within the report using an image report item. In this post I will cover some of the details needed to work with images that are inserted using the Image report item.

The image report item can retrieve images in four different ways. 1 -Through a URI, 2 – as an image in the resource folder, 3 – as an embedded image, 4 -or by using a dynamic image. Each of these methods is described below with examples. In addition some of the examples use onCreate scripts written in JavaScript. While these examples use JavaScript, they could also have been written in Java.

URI Images
The first way is to retrieve an image with the image report item is to use a URI specification. This method is pretty straight forward and the value can be entered as a constant or as a JavaScript expression. Constants are processed faster by the engine but are harder to make dynamic. An example of a constant expression for a URI image would be as follows:



http://www.eclipse.org/eclipse.org-common/themes/Nova/images/eclipse.png

Note: Do not put quotes around the expression unless JavaScript Syntax is selected. An example of using a JavaScript expression is presented below.



if( params["dynamicimage"].value == true ){
"http://www.google.com/intl/en_ALL/images/srpr/logo1w.png";
}else{
"http://www.eclipse.org/eclipse.org-common/themes/Nova/images/eclipse.png";
}
This expression checks the value of the dynamicimage report parameter, and then based on its value, sets the value of the URI.
The URI can also be set using an onCreate event handler for the image report item.  The syntax for this approach would look like:
this.URI = "http://tomcat.apache.org/images/tomcat.gif";

//for a local file use: 
//this.URI = "file://C:/test/birtlogo.png";

Resource Folder Images
BIRT uses a resource folder for storing report libraries, style sheets, images, jars, js files, properties files or virtually any file that you will need access to at runtime. While in the design environment the resource folder location can be set using the Windows->Preferences->Report Design->Resource setting. This can be set for the entire workspace or on a per project basis. At runtime you can set the resource folder in the web.xml if you are using the viewer. If you are using the engine API you can set the resource folder using the EngineConfig class’ setResourcePath method. When using a resource folder image, all that is needed is to specify the image name as it is defined in the resource folder. You can also set a JavaScript expression for the image name. For example:



if( row["QUANTITYORDERED"] > 30 ){
"green.png";
}else if( row["QUANTITYORDERED"] > 25  && row["QUANTITYORDERED"] <= 30){
"yellow.png";
}else{
"red.png";
}

This expression checks the row data to determine which resource folder image should be rendered. The same type of checks can be made if you are using the onCreate script event for the image element.



var myqty = this.getRowData().getColumnValue("QUANTITYORDERED");
if( myqty > 30 ){
 this.file = "green.png";
}else if( myqty > 25  && myqty <= 30){
 this.file ="yellow.png";
}else{
 this.file="red.png";
}

One thing to note in the above is that the column value QUANTITYORDERED is the binding column name, not the dataset column name. See the binding tab on the table in the attached example.
Images can also be placed in jar files within the resource folder. If your image exists in a jar file, you can use a script expression similar to the following to specify the image to retrieve.



var jarfile = reportContext.getResource("birtimages.jar");
myfulljarimage = "jar:"+jarfile.toString()+"!/green.png";
myfulljarimage;

The getResource method of the reportContext object is used to return the location of a file in the resource folder. Using the location of the file and the jar protocol, the image can be specified.

Embedded Images
BIRT allows images to be encoded directly into the xml report design. Images can be added by right clicking on the embedded images icon in the outline view of the report and selecting “New Embedded Image”. After selecting the image, the outline view is updated and the data for the image is encoded in to the design. You can also add embedded images to the report using the add image button of the image report item editor.

Once the images are embedded into the report, you can add the image report item to the desired location, choose the embedded image radial, select the image name and click the insert button.

If you wish to change the image dynamically, this can be done using an onCreate script. In the onCreate script specify the image name using the imageName property.



this.imageName = "eyellow.png";

Dynamic Images
Dynamic images allow Blob images to be inserted into the report. Typically this type of image is tied to a data set column through either the image’s dataset bindings, or the container element’s bindings (eg Table). The sample database, which is delivered as part of BIRT, contains a Blob type column in the PRODUCTLINES table. The example report used in the post has an example of using this column in conjunction with the image report item.

A developer can also use an onCreate event script to set the image data. When doing this, the image data should be in a byte[]. Presented below is an onCreate script that uses the ImageIO class to read a file, a URL, an image from the resource folder, or an image in a jar file in the resource folder. Uncomment the section of the script for the desired image location.



importPackage(Packages.java.io);
importPackage(Packages.java.lang);
importPackage(Packages.java.net);
importPackage(Packages.javax.imageio);

//File Based
//var myfile = new Packages.java.io.File("c:/test/green.png");
//var img = ImageIO.read(myfile);  

//URL Based
//Jar image in resource folder
var jarfile = reportContext.getResource("birtimages.jar");
var myfulljarimagestr = "jar:"+jarfile.toString()+"!/red.png";
var myurl = new Packages.java.net.URL(myfulljarimagestr);

//Image in resource folder
//var myurl = reportContext.getResource("green.png");

//Image at url
//var myurl = new Packages.java.net.URL("http://www.eclipse.org/eclipse.org-common/themes/Nova/images/eclipse.png");

var img = ImageIO.read(myurl);
bas = new ByteArrayOutputStream();
ImageIO.write(img, "png", bas);
this.data = bas.toByteArray();

The example used for this post is available at Birt-Exchange. To setup the example, copy the birtimages.jar and the three supplied images to your resource folder.

BIRT Flash and Gadget Scripting

2010-08-20T08:52:00.000-07:00

In my last post I blogged about how Chart Scripting works in BIRT. If you are using Actuate BIRT, you also will have access to Flash Charts and Gadgets. Scripting for these two report items is very similar to the standard Chart scripting model.

Flash Charts
Currently Flash charts support 14 script event triggers that can be hooked to make chart modifications.

The event firing order is shown below.

As you can see the order is very similar to that of normal BIRT charts. The before and after dataset filled events are fired first for each dataset (category and value). Next the beforeRendering event is fired and then the before and after draw series events are fired for each series. Between the before and after draw series events the before and after draw data point events are fired for each point in the series. The before and after draw series events (and the events contained in them) are fired for each series in the chart. After all series are processed, the before and after draw effect events are fired for each effect in the chart. Effects can be used to alter the chart at runtime, allowing font manipulation, blurring, glowing, shadowing, beveling, and animation of different objects of the chart. Effects are added to the chart using the effects editor.

Using the beforeDrawEffect event script you can alter any of the effects added to the chart. For example to turn off the shadow effect in the above chart you could use the following script.



function beforeDrawEffect( effect, fcsc )
{
var effectName = "MyTitleEffect";
if ( effectName.equals( effect.getAction().getName() ) ){
if( effect.getAction().getShadow() != null ){
effect.getAction().getShadow().setEnabled(false);
effect.getAction().getFont().setEnabled(false);
}
}
}

The getEffect().getAction().getName() call returns the name of the effect as defined in the effect editor. This can be used to determine which effect definition your script is operating on. The getAction allows access to the different effect features. Note that if the effect is not enabled the getter method for the effect will return null. In the above script we first check to see if the getShadow method returns null before turning it off.

Finally the afterRendering event is triggered.

These events function much the same way as described in my earlier post. You will notice that event function prototypes are just a little different. For example instead of a chart and icsc parameter you will get a flashChart and fcsc parameter in certain events. For practical purposes these are just extended chart and icsc objects and still provide most of the standard object features. For example to set the chart title to the value of a report parameter using the reportContext, you could use a script like the following.



function beforeRendering( flashChart, fcsc )
{
var parmChartTitle = fcsc.getExternalContext().getScriptable().getParameterValue("MyChartTitle");
flashChart.getChart().getTitle().getLabel().getCaption().setValue(parmChartTitle)
}

Flash Gadgets
BIRT Flash Gadget report items are used to display data in a unique dynamic graphic. Currently Actuate BIRT supports thermometer, cylinder, bullet, spark line, meter gauge or linear gauge gadgets. These gadgets also support server side scripting.

Twelve event triggers are supported and can be used to alter how the gadget is displayed. The events that are triggered will depend on the gadget and which features the gadget is using. For example this meter gadget:

Produces the following event order.

The beforeRendering event is called first and can be used to modify the flash gadget before it is rendered. Next before and after draw region events are trigger for each of the three regions in the meter gadget. This gadget contains two thresholds, so the before and after threshold events are triggered next for each threshold. The gadget also contains two needles so the before and after draw needle events are fired. The threshold label contains a font effect and the threshold areas are animated. This produces before and after draw effect triggers for each. Finally the afterRendering event is triggered.

Retrieving Gadget Values
BIRT Flash Gadgets use value definitions to link the gadget to a BIRT dataset. The definitions are assigned in the Gadget Editor. The runtime values for these definitions can be retrieved in script using the gadget object. For example, in the beforeRendering you could use the following script:



function beforeRendering( gadget, fgsc )
{
 var vals=gadget.getResultValues();
 for( i = 0; i < vals.size(); i++ ){
  if( vals.get(i).getValue() > 20 ){
   //do something
  }
 }
}

The number of result values will depend on the gadget. For example, In a Spark Line gadget there will be multiple values. In a meter gadget, there will be a result value for each needle value.

Region Events
You can customize the colors, transparency, labels, and range values of any region using the beforeRendering or beforeDrawRegion scripts. See the example below.



function beforeDrawRegion( region, fgsc )
{
 if( region.getLabel().equals("A") ){
  region.setColor("00ff00");
 } 
   //Display value range of region.   
     region.setLabel( "(" + region.getStartValue() + ", " + region.getEndValue() + ")" ); 
    
}

function beforeRendering( gadget, fgsc )
{
 //First Region
 gadget.getRegion().get(0).setEndValue(25);
 //Second Region
 gadget.getRegion().get(1).setStartValue(25);

Threshold Events
Thresholds, like regions can also be customized using script. Virtually anything that is set in the designer can be changed in an event trigger. For example:



function beforeDrawThreshold( threshold, fgsc )
{
  if( threshold.getLabel().equals("MyThreshold") ){
   threshold.setShowValueInside(true);
   threshold.setShowValueOnTop(false);
   threshold.setStartValue(10);
   threshold.setColor("0000ee");
  // Display the value range of threshold.
   threshold.setLabel( "(" + threshold.getStartValue() + ", " + threshold.getEndValue() + ")" );
  }
}

function beforeRendering( gadget, fgsc )
{
 gadget.getThresholds().get(0).setMarkerColor("ff0000");
}

In these scripts, we change the starting value, color, label and label location in the beforeDrawThreshold. The marker color is also changed in the beforeRendering script.

AddOn Events
BIRT Gadgets support the concept of an AddOn. An AddOn allows the designer to place images, text, and various shapes on top of the gadget. If the gadget contains an AddOn the before and afterDrawAddOn events will be triggered, allowing you to customize the AddOn at runtime. For example, the following script customizes two AddOns.



function beforeDrawAddOn( addOn, fgsc )
{
 // Change add-on styles. 
 if ( addOn.getName().equals("TitleAddOn") )
 {
  addOn.setLabel( "Meter Gauge" );
  addOn.setFontColor( "ff0000" );
  addOn.setFontSize( 28 );
  addOn.setY( 35 );
 }
 else if ( addOn.getName().equals( "ArcAddOn" ) )
 {
  addOn.setFillColor( "ffff00" );
 }
}

AddOns can even be created and placed on the gadget at runtime. For example the following script adds a text AddOn to the gadget using the beforeRendering event.



function beforeRendering( gadget, fgsc )
{
  importPackage( Packages.com.actuate.birt.flash.gadgets );
  importPackage( Packages.com.actuate.birt.flash.gadgets.impl );
  
  // Add a text add-on.
  var textAddOn = GadgetsFactory.eINSTANCE.createTextAddOn();
  textAddOn.setAddOnType( AddOnType.TEXT );
  textAddOn.setName("DescAddOn");
  textAddOn.setShowAddOn(true);
  gadget.getAddOns().add( textAddOn );
  gadget.setZOrderPosition(1);
 
 textAddOn.setLabel("This sample demonstrates how to add an add-on by scripting.");
 textAddOn.setX(2);
 textAddOn.setY(20);
 textAddOn.setFontSize( 12 );
 textAddOn.setHorizontalAlignment( HorizontalAlignmentType.LEFT );
 textAddOn.setVerticalAlignment( VerticalAlignmentType.TOP );
 textAddOn.setWrap( true );
 textAddOn.setTextBoxBorderColor("000000"); //Black
 textAddOn.setTextBoxBackgroundColor("c0c0c0");
 textAddOn.setWrapMaxWidth( 30 );
 textAddOn.setWrapMaxHeight( 50 );
 
}

Needle Events
If your gadget contains a needle, the before and afterDrawNeedle events will be triggered. Using script the needle can be customized. The size, color, shape, and various other properties of the needle can be customized. These events are passed a NeedleWrapper instance, which can be used to get the specific needle type. For example the following two scripts differentiate between a normal gadget needle and a meter gadget needle.



function beforeDrawNeedle( needleWrapper, fgsc )
{
   importPackage( Packages.com.actuate.birt.flash.gadgets );
   importPackage( Packages.com.actuate.birt.flash.gadgets.impl );
   // Change needle styles.
   needleWrapper.getNeedle().setShape( Shape.DIAMOND );
   needleWrapper.getNeedle().setFillColor("2cf83a");
   needleWrapper.getNeedle().setBorderColor("007f00");
}

function beforeDrawNeedle( needleWrapper, fgsc )
{  
   //Set Needle size to 25%
   needleWrapper.getMeterNeedle().setSize(25);
   needleWrapper.getMeterNeedle().setBackgroundColor("ff0000");
}

Effect Events
The effect events were described above in the flash charting section.

Several examples used in this post are available at BIRT-Exchange.

BIRT For Perforce

2010-08-16T15:48:00.000-07:00

I recently stumbled across a project that has BIRT reports about Perforce. It looks like if you are using Perforce for your version control, you can now use BIRT reports to gain insight into that system.

http://public.perforce.com/wiki/BIRT_Reports

BIRT Charting – Scripting Overview

2010-08-12T11:01:00.000-07:00

The BIRT Chart Engine currently supports building and running charts within the BIRT designer or externally. The engine is fully extensible using the Eclipse extension mechanisms and supports client side interactivity and server side event scripting. Fourteen main chart types, such as bar charts, line charts, and scatter charts are supported. Additionally most chart types support many subtypes such as stacked bar charts, 2D with depth, or 3D charts. When using the chart engine within BIRT the charts can be rendered as PNG, JPG, BMP, or SVG.

The chart engine also supports a sophisticated server side event model that allows the developer to customize the charts dynamically. This post is an overview of most of the chart scripting events available.

If you are interested in learning more about client side chart scripting, see these posts:
ClientSide Script:
Calling Client Side JavaScript from a BIRT Chart
More on Chart Interactivity

General BIRT Server Side Scripting
BIRT Chart event scripting is based on the standard BIRT report scripting model. A primer for report scripting is available here. When the BIRT report engine processes reports they are executed in two phases (Generation and Presentation). The generation phase connects to data sources collects and processes the values and creates the report items. The presentation phase renders the content to the particular output (HTML, paginated HTML, PDF, PPT, XLS, DOC, or PS). These phases can be executed in one or two processes, depending on how you call the engine.

If you use the Report Engine API (RE API), the RunAndRenderTask is one process. To run it in two processes you would use a RunTask and then a RenderTask. If you are using the BIRT Viewer, the /Run and /Preview mappings use one process and the /frameset mapping uses two processes. This concept is very important to understand when scripting as it affects the order in which the events are triggered. When using one process the event order for a data item would look something like:

1st instance
onPrepare
onCreate
onRender
2nd instance
onCreate
onRender.

The same data item with two processes would look like:

1st instance
onPrepare
onCreate
2nd instance
onCreate

onRender first instance
onRender second instance

Using two processes offers many advantages. First a binary file called the report document (.rptdocument) is created which can be rendered many times at a later date without re-executing all the queries. It is also required to support TOC bookmarks and paginated HTML.

Chart Server Side Scripting
When using charts in a BIRT report, the engine supports over thirty events. These events can be used to change the data, interactivity, or presentation of the chart. All of these events are fired in the presentation phase (at render time) of the report and can be written in Java or JavaScript.

It is possible to change chart properties at generation time, but these changes must be made in a report event that happens prior to the chart being created, like the beforeFactory event. This approach is described here and here.

It is vital to understand when chart events are fired, if you plan on making script changes to your chart. Take for instance the following chart.

This is a standard Bar chart with a marker line and curve fitting line. If two processes are used to generate the report that contains this chart, the following event firing order will be used.

This diagram shows most of the available events, but not all events are fired for every chart type. For example before and afterDrawMarker events are only fired for chart types that support makers and these events are usually fired in between the before and afterDrawDataPoint scripts. The beforeDrawSeriesTitle event only fires for Pie charts.

Notice the chart events do not start until after the beforeRender report level event.

Chart Script Context
Before getting into each of the events, a good understanding of the chart script context object will be helpful. All BIRT Chart events are passed a chart script context object. This object will be labeled icsc in the function definition. You can use the chart script context object to get the current instance of the chart model by calling:



icsc.getChartInstance();

You can also use it to get the reportContext that is associated with all other report scripting events. See the scripting primer referenced above for more details. This object can be used to get parameter values, resource values, locales, the current http request, global variables, page variables, etc. To access these functions with a JavaScript event use the following:



rpCtx = icsc.getExternalContext().getScriptable();

This is equivalent to the reportContext variable. So to get a report parameter value, use:



rpCtx.getParameterValue(“MyParameter”);

or to access the http request use (this only works in the Viewer unless you put the http request object in the report engines App Context):



rptCtx.getHttpServletRequest().getRequestURL();

If you are using a Java Event handler use:



IReportContext rpCtx = (IReportContext)icsc.getExternalContext().getObject();

Data Set Filled Events
The first set of chart events that fire are the data set filled events. These events are fired when data organizing and generation of runtime series is occurring for the chart. In These events you can change many properties of the chart model, such as series expressions, grouping, labels, formatting, and series visibility. These events are fired once for the category series and once for each runtime series that is generated based on how the chart is designed. Generally you will get one runtime series per design time series and one additional one for the category series. So if you define a bar chart with product code on the x-axis and quantity ordered on the y-axis, this would produce two runtime series. Each series would contain an array of values. For example ProdA, ProdB, and ProdC may be the category series and 55, 98, and 32 may be the value series. If the chart also contained a line series then this would constitute on additional runtime series containing its values. If you use the optional grouping feature this could generate many runtime series, depending on the number of groups the optional grouping expression produced. In the above example, if the following expression was entered for the optional grouping.



if( row["QUANTITYORDERED"] > 50 ){
"high";
}else{
"low";
}

This would produce a total of three runtime series. 1 (ProdA,ProdB,ProdC), 2 ( 55, 98, null) and 3 (null ,null, 32).

Note that all series have to have the same number of points. In the afterDataSetFilled script these values can be check and or modified.

beforeGeneration Event
The beforeGeneration event is executed before chart building begins and after all series data points have been created. You can make changes to the chart model here and can even alter the datasets that the chart uses. In the data set filled events, many runtime series may have been generated. Every series in a chart will have a unique series identifier. You can specify this on the third tab of the chart wizard. If you use optional grouping and many runtime series are generated for each design time series, a new series identifier will be created for each runtime series. To interrogate these series use code similar to the following (Chart With Axis Example):



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

var ySeries = ySeriesDef.getRunTimeSeries();
var numberofrunseries = ySeries.size();
//get the first runtime series identifier
ySeries.get(0).getSeriesIdentifier();

Computation Events
The before and afterComputations events are called next. These events are called just before and right after all the calculations for the chart’s rendering properties are processed. These computations include all bounds objects for the chart, the series rendering hints, and data point hints, which store the plot location and values for each series. Using these scripts these values can be modified before the chart is actually rendered.

afterGeneration/beforeRender Event
These events are fired after the chart is built but before it renders each part of the chart. When the chart engine is building it stores all information in the GeneratedChartState object. This object is passed to these methods and can be used to make changes before the chart is rendered. You can use the following code to get the plotComputations object that was populated in the computations event:



compu =gcs.getComputations();

You can even change how the chart engine processes interactivity triggers. For example assume you have a class that implements the IActionRenderer interface.



package my.action.handler;
import java.io.Serializable;
import org.eclipse.birt.chart.computation.DataPointHints;
import org.eclipse.birt.chart.event.StructureSource;
import org.eclipse.birt.chart.event.StructureType;
import org.eclipse.birt.chart.model.attribute.ActionType;
import org.eclipse.birt.chart.model.attribute.TooltipValue;
import org.eclipse.birt.chart.model.data.Action;
import org.eclipse.birt.chart.render.ActionRendererAdapter;
public class MyActionHandler extends ActionRendererAdapter implements Serializable{

 private static final long serialVersionUID = 1169308658661902989L;

 public void processAction( Action action, StructureSource source )
 {
  if ( ActionType.SHOW_TOOLTIP_LITERAL.equals( action.getType( ) ) )
  {
   TooltipValue tv = (TooltipValue) action.getValue( );
   if ( StructureType.SERIES_DATA_POINT.equals( source.getType( ) ) )
   {
    final DataPointHints dph = (DataPointHints) source.getSource( );
    String MyToolTip = "My Value is " + dph.getDisplayValue() + "--" +dph.getBaseDisplayValue();
    tv.setText( MyToolTip );
   }
  }
 }
}

You could instantiate an instance of this class in the beforeFactory event of the report:



importPackage(Packages.my.action.handler);
MyActionRenderer = new MyActionHandler();
reportContext.setPersistentGlobalVariable("myactionrenderer", MyActionRenderer);

And then set it in the beforeRender event like:



mar = icsc.getExternalContext().getScriptable().getPersistentGlobalVariable("myactionrenderer");
gcs.getRunTimeContext().setActionRenderer(mar);

DrawBlock Events
Charts in BIRT are made up of rendering areas called blocks. Each block will have properties such as rendering bounds, anchor points, outline properties, background properties, and child blocks. The whole chart is the main chart block and within this block is the title block, the plot block and the legend block.

The before and afterDraw block events are called multiple times, once for each chart part that constitutes a block.

The before and afterDraw block events are first called for the whole chart, the title block, plot block, and finally for the legend block. Nested within the plot block and legend block other events will fire as illustrated in the event diagram. The plot block events are fired once for each runtime series as well. So if you have 3 runtime series, the before and afterDrawBlock event will be called three times for the plot block.

To know which block the event is firing for you can use a script similar to:



 if ( block.isLegend( ) )
 {
  block.getOutline( ).setVisible( true );
  block.getOutline( ).getColor( ).set( 21,244,231 );
  block.setBackground( ColorDefinitionImpl.YELLOW( ) );
  block.setAnchor( Anchor.NORTH_LITERAL ); 
 }
 else if ( block.isPlot( ) )
 {  
 }
 else if ( block.isTitle( ) )
 {  
 }
 else if ( block.isCustom( ) ) //Main Block
 {
 }

You can use these events to modify the calculated bounds of any block, but this may result in unattractive charts. To change the location of the legend the following script could be used.



 if (block.isLegend())
 {
  var wid = block.getBounds().getWidth();
  var lft = block.getBounds().getLeft();
  
  block.getBounds().setLeft(lft-20.00);
  block.getBounds().setWidth(wid+20.00);
 }

Marker Range and Line Events
The before and afterDrawMarker range and line events are called before any of the series are drawn. These events are only called for charts with axis that actually contain marker ranges (or lines). Using these events the marker ranges (or lines) can be modified. By default the location of the markers are set in the chart builder, but you can set the location using an index like:



markerLine.setValue(NumberDataElementImpl.create(intcountformaker));

The index is associated with the runtime series data point index and not the data point value. If the index is set to 0 the marker will be set to the first data point. You can use this in combination with other events like the afterDataSetFilled event to make the marker dynamic.

Draw Series Events
For each runtime series that is generated, the before and afterDraw series events will be fired. You can use the series identifier to determine which series is being processed. You can also check the specific type that of series that is being rendered.



 if( series.getClass() == LineSeriesImpl ){
  series.getLineAttributes().setThickness(5);
 }
 if( series.getClass() == BarSeriesImpl ){
  if( series.getSeriesIdentifier() == “Series 1”){
  }
 }

Also note that this event is called for the category series.

Within these events you can modify the series before it is rendered. For example if you want to change a drill through hyperlink to point to a different report you could use the following script.



 triglen = series.getTriggers().size();
 if( triglen >0 ){
  mytarget = series.getTriggers().get(0).getAction().getValue().getURLValues( ).get(0).getBaseUrl();
  newtarget = mytarget.replace("reporttarget1.rptdesign", "reporttarget2.rptdesign");
         series.getTriggers().get(0).getAction().getValue().getURLValues( ).get(0).setBaseUrl(newtarget);

 }

You can also get all the data points for the series by using script like the following:



 if( series.getClass() == BarSeriesImpl ){
  var pts = isr.getSeriesRenderingHints().getDataPoints();
  for( i=0; i< pts.length; i++ ){
   var mydp = pts[i];
   if( mydp.getOrthogonalValue() > 35 ){
    //do something
   }  
  }
 }

DataPoint and Data Point Label Events
For each runtime series that is not a category series, the before and afterDrawDataPoint and before and afterDrawDataPointLabel events are fired. These occur between the before and afterDrawSeries events. These events can be used to modify how the data point and label are rendered.

The fill object passed to the before and afterDrawDataPoint events will be an instance of one of the following classes depending on how you have setup the palette.

GradientImpl
ColorDefinitionImpl
ImageImpl (EmbeddedImageImpl and PatternImageImpl extend ImageImpl)

It is important to know which type you are dealing with if you plan on making changes to the fill object. You can check the fill type with script similar to this:



 if( fill.getClass().isAssignableFrom(GradientImpl)){
        fill.setStartColor(ColorDefinitionImpl.create( 0, 0, 255 ));
        fill.setEndColor(ColorDefinitionImpl.create(255,255,225 ));
 }

You can set the fill object based on the data point value by using a script like (Assumes Color Fill):



     val = dph.getOrthogonalValue();
      if (val == 10){
            fill.set(255, 0, 0);
      }

Using the data point label scripts you can modify the label format and value.



var newlabel = label.getCaption().getValue().replace(",", "'");
label.getCaption().setValue(newlabel);

 if( dph.getBaseDisplayValue() == 50 ){
  label.setVisible(true);
  
  label.getCaption().getFont().setBold(true);
  label.getCaption().getFont().setSize(14);
  label.getCaption().getFont().setName("Arial");
     }else{
      label.setVisible(false);
     }

Curve Fitting Events
If the series contains a visible curve fitting line, the before and afterDrawFittingCurve events will be trigged after all the data point and data point label scripts have fired. You can use this event to modify the line attributes and label properties for the fitting curve.

Axis Title and Axis Label Events
After all series have been rendered the before and afterDrawAxisLabel events are fired for every label that appears on the axis. The before and afterDrawAxisTitle events are then fired. This process starts with the category axis and then proceeds for each value axis. You can use these events to modify the labels that are rendered. The axis type can be checked to determine which axis fired the event.



 //LINEAR_LITERAL
 //LOGARITHMIC_LITERAL
 //TEXT_LITERAL
 //DATE_TIME_LITERAL
 if( context.getExternalContext().getScriptable().getParameterValue("NewParameter") == "date"){
  if (axis.getType() == AxisType.TEXT_LITERAL)
  {
   value = label.getCaption().getValue();
   var dtf = new SimpleDateFormat("MM/dd/yy");
   var dt = new Date(value);
   var fn = dtf.format(dt);
   label.getCaption().setValue(fn); 
  }
 }
 You can also check the axis title to determine which axis fired the event.
 if( axis.getTitle( ).getCaption( ).getValue( ) ==
  "myYaxisTitle" )
 {
  label.getCaption( ).setColor( 
   ColorDefinitionImpl.BLUE( ) );
 }
 if ( axis.getType( ) == AxisType.DATE_TIME_LITERAL )
 {
  label.getCaption( ).setColor( 
   ColorDefinitionImpl.RED( ) );
 }

Legend Item Events
The final set of events that are fired that can affect the chart are the before and afterDrawLegendItem events. These events can be used to customize the look of the chart legend.

This event is passed the LegendEntryRenderingHints (lerh) object and the bounds for the specific entry. The bounds object is for legend item graphic and not the text. Using these objects you can customize the legend. You can hide an entry using the bounds object.



 if( lerh.getLabel().getCaption().getValue().compareToIgnoreCase("series3") == 0 ){
  bounds.setHeight(0);
  bounds.setWidth(0);
  lerh.getLabel().setVisible(false);
 }

You can modify the fill object using the lerh.getFill() function and modify the label using the lerh.getLabel() function.



 importPackage( Packages.org.eclipse.birt.chart.model.attribute.impl );
 label = lerh.getLabel();
 labelString = label.getCaption().getValue();
 if( labelString == "series2" ){
  label.getCaption( ).getColor( ).set( 32, 168, 255 );
  label.getCaption().getFont().setItalic(true);
  label.getCaption().getFont().setRotation(5);
  label.getCaption().getFont().setStrikethrough(true);
  label.getCaption().getFont().setSize(12);
  label.getCaption().getFont().setName("Arial");
  label.getOutline().setVisible(true);
  label.getOutline().setThickness(3); 

  var mycolor = ColorDefinitionImpl.BLUE();
     r = mycolor.getRed();
        g = mycolor.getGreen();
        b = mycolor.getBlue();
        lerh.getFill().set(r, g, b);

 }

You can check the fill object type before modifying it as described in the DataPoint and Data Point Label Events described earlier.

Chart Scripting Examples
Here are some example reports/posts that illustrate using the chart scripting model.
BIRT Resizing Charts
BIRT - Reversing a Chart Scale
Resize Pie Chart based on optional grouping count
Add spacing to stacked bar optional grouped chart
Turning a Chart series off in script
Set Chart Axis Label Interval with Script
Using Chart Script to Define a specific series color
Chart Script to Alter Palette - Gradient Pie
Adjust BAR Location in Bar Chart

Functions and Controls Moves to Eclipse Labs

2010-08-03T15:04:00.000-07:00

Don't you love it when technology just works? I recently had this experience when I moved a couple of BIRT projects to Eclipse Labs. I have moved all of my BIRT projects that were on Google Code over to the Eclipse Labs section of Google Code. You can access them here:

The one question might be why create an update site that is separate from the project sites? Well the short answer is that I want to make it easy for someone to get access to the projects we have created from a single site. In addition, it is easy for me to add more content without having to modify the existing versions on the projects.

In the next couple of weeks, I hope to add a couple of new features to the update site that will make it easier to create team based reporting projects.

Whats the Difference Between dataSetRow["FIELD"] and row["FIELD"]

2010-07-26T09:38:00.000-07:00

One of the most common questions for people that are new to BIRT is about how to ask data from the DataSet in the report. The question is when building expressions should I use dataSetRow["FIELD"] or row["FIELD"]?

So let me see if I can set the record straight. When data is acquired, it is acquired by a DataSet, so the following query in a JDBC DataSet will create a three field resultset:

select CITY, STATE, COUNTRY 
from CUSTOMERS

Any script or expressions written on the DataSet will be written to use the format

row["FIELD_NAME"];

So if we add a computed column to the DataSet called compCityState, the expression would look like this.

Once a computed column is created, you can reference that computed column using the same row syntax. So in the OnFetch method you could add this message to log the value of the computed column.

Packages.java.lang.System.out.println(row["compCityState"]);

The other place that you can access variable on the DataSet is through ReportItem binding. In most cases, this means Table Binding where you have attached a table to a DataSet. In general, when you use BIRT you associate a Table with a DataSet. We say that the Table is bound to the DataSet.

When a DataSet is dragged to the Layout editor, BIRT automatically does the data binding and creates a bound column for each field and computed column in the DataSet. The following shows a table and its Binding.

You will notice that all of the expressions use the term dataSetRow, which means this value is pulled from the DataSet. Now for the tricky bit, any field that is bound to a Table can be used in another table binding. So if we wanted to create a field that has City, State and Country, we could either:
a) go back to the DataSet
b) add a new table binding

When you add a binding to a table you are brought to the expression builder. In this first example, I am creating a table binding that gathers data straight from the DataSet.

Because I am referencing the DataSet directly the expression uses the dataSetRow syntax.

In the next example, I will use the previously established bindings to build the expression. In the expression builder I will select Available Column Bindings and the Table and then select the fields. You will also notice that the Table Binding has access to any of the previously bound fields and a special RowNumber field.

The important thing is that the syntax to access those values is to use row["FIELD_NAME"]

So the short answer is, dataSetRow syntax references the original values from the DataSet, whereas the row syntax references the bound column values.

Now for a quick test, this should be easy.

Imagine that I change the expression of the CITY expression to look like this, and all else remains the same.

If the values for the row are:
City: Kalamazoo
State: MI
Country: USA

What will a DataItem that is showing rowCityStateZip display?
What will a DataItem that is showing tablCityStateCountry display?

The answers will be after a short shameless promotion of my companies BIRT training program. We have designed a modular training program that is focused on teaching you how BIRT works. You can take one module or all of them. The focus of our training is on how BIRT works, so that when you finish you really understand what is going on in the product.

Our training can be taken on-site, or through remote sessions of between two and four hours each. We are also happy to work with your team to customize the training to match your companies needs. If you are interested, please visit our web site and have a look.

Answers:
rowCityStateZip: { Kalamazoo }, MI USA
tablCityStateCountry: Kalamazoo, MI USA

Remember, dataSetRow syntax (as used in tablCityStateCountry) goes back to the original data. Row syntax use the table binding.

Manipulating Chart Legends in Event Handlers

2010-07-19T12:02:00.000-07:00

Recently I had the opportunity to figure out how to manipulate sizing, positioning and text wrapping of chart legends so I thought I'd share what I learned.

If you have a chart with legend items that don't fit in the available space, BIRT will do one of two things, depending on the wrapping width option. (Wrapping width is found on the legend layout dialog). If the wrapping width is set to zero, BIRT will simply truncate the legend item text and optionally append an ellipsis. (The ellipsis option is located on the legend entries dialog).

If the wrapping width is set to a positive value, BIRT will word-wrap the text. Unfortunately when it does this, it doesn't check the vertical boundaries and long items can end up overlapping.

Another downside is you have to specify a hard width within which to wrap. It won't simply wrap based on the amount of space that's available. On top of that, my client had some special requirements about how the Thai characters should be wrapped. So I dug into the chart event handlers to see what I could do.

It turned out I could do a lot, but I had to pick the right event handler. My first thought was to use beforeDrawLegendItem. It looked perfect because of the Bounds parameter. However, it turned out that was not the bounds of the text area, but of the colored rectangle, which didn't help me much. Additionally I couldn't manipulate the size and position of the legend items within that handler and have it stick. The horses had already left the barn so to speak.

The beforeRendering handler was much better. In it I could manipulate the size, position and text of each legend item. Following are the the technical details.

The first argument to the event handler function is a GeneratedChartState object (which I'll call gcs). Using gcs.getRunTimeContext(), you can get the RunTimeContext object (rtc). Then using rtc.getLegendLayoutHints() you get the LegendLayoutHints object (llh) which tells you about the legend as a whole. Particularly llh.getLegendSize() tells you how big BIRT wants to make the legend. Finally llh.getLegendItemHints gets you an array of LegendItemHints (liha), which gives you access to each legend item. The number of legend items is liha.length. The text for each item is lih.getItemText().

So how much height is available for the whole legend? You can get that with gcs.getPlotComputations().getPlotBounds().getHeight(). The width of the legend is llh.getLegendSize().getWidth(). I didn't need to change the width so I didn't try to find out how to do that. I'm not sure how BIRT allocates horizontal space to the legend vs the chart itself. That may present itself as a future exercise.

For my project I had to wrap this text according to the space that was available, so I needed to be able to measure the pixel width of a string of characters. To do this you need to instantiate BIRTChartComputation. The constructor takes no arguments so it's simple. I'll call my instance bcc. Next you need the font height, which you can get from bcc.computeFontHeight. This method needs an IDisplayServer and a Label. You can get the IDisplayServer from gcs.getDisplayServer() and you can create a temporary Label with GObjectFactory.instance().createLabel(). The method with compute the font height based on the text in the label. Finally, you get the overall size of a string of text with bcc.computeLabelSize, which you pass an IDisplayServer, a Label and a font height. This is a fairly expensive operation so it's best to use a binary search to look for a wrap point.

Once a new version of the text has been computed, you can simply insert it back into the LegendItemHint using lih.setItemText(). Also the item height can be set with lih.itemHeight(). Finally, if you want an ellipsis to be appended you need to set the valid item length with lih.validItemLen() to the character position where you want the ellipsis to go. If you set it to zero or a value greater than the length of the label, no ellipsis will be appended.

Since I also needed to change the overall size of the legend, I wanted a setLegendSize method in LegendItemHints, but no such method exists. In fact, the class is mostly immutable. Fortunately it's possible to instantiate a new LegendItemHints with a new size and pass it to the RunTimeContext with rtc. setLegendLayoutHints().

An that's it. Fun, huh? Ok you can stop yawning. Here's what my new legend looks like:

I know you can't do everything in event handlers, but this is more than I thought I'd be able to do when I started. I was pleasantly surprised.

BIRT and OLAP

2010-07-14T08:56:00.000-07:00

BIRT Introduced OLAP style data cubes and crosstabs in version 2.2 and while they have been around for some time we still get a lot of questions on how to use and manipulate them. Below are just some of the resources that have been posted to BIRT Exchange that should help you with cubes and crosstabs.

Introduction Resources
To get an idea of what a BIRT cube is and how to tie it to a crosstab report item, take a look at this article which provides a detailed write-up of the technology and supplies some examples.

To see a recorded demonstration of a crosstab style report being build see this tutorial video.

Event Based Scripting Resources
BIRT provides event based server side scripting for almost all report items, including crosstabs. A detailed blog post is available here with an example that demonstrates implementing a crosstab with event handler script.

Client Side Crosstab Scripting
BIRT supplies a Text report item that allows formatted HTML to be inserted into BIRT reports. Text elements can also be used to insert client side script that will execute while viewing the report in HTML. The Text element can be used in conjunction with a crosstab to add client side script to the crosstab. As an example of this take a look at these on BIRT Exchange. One of the examples animates the crosstab by iteratively changing the background color of a cell based on its value while the other inserts mouse over events to highlight specific cells.

Using the DE API in conjunction with a Crosstab
The BIRT Project provides the Design Engine (DE API) to construct report, template and library designs. This API is used by the designer when building BIRT content. Not only can this API be used in a Java project but can be called from a Java/Java Script event handler to modify a currently running report. There are many examples of this on BIRT Exchange. A couple of examples that are relevant to cubes and crosstabs are listed below.

This example uses report parameters and a beforeFactory JavaScript event to change the sort order for a crosstab.

Another example of using this approach is located here. This example contains a report with no graphical content, but does contain a datasource, dataset, and data cube. It uses report parameters and a beforeFactory JavaScript event to construct a crosstab based on the parameters.

Building a crosstab with the API
If you are using the DE API to create reports from your Java application and wish to add crosstabs to your reports this example illustrates building a data cube and adding a crosstab to a report using the API.

Extended Capabilities
If you are interested in further capabilities, Actuate 11 which will be released this fall, provides a new feature called the Actuate BIRT Data Analyzer. This product is a zero footprint browser based BIRT cube analyzer. It can be used with existing BIRT reports that contain cubes to add, modify, re-order, or remove dimensions and measures without having to re-execute the report.

In addition to the above, the Data Analyzer can be used to pivot, filter, sort, and add computed measures and aggregates to the crosstab, all from within the browser without re-executing the report.

If you are interested in trying out this feature download the latest milestone build of the Actuate BIRT Report Designer from the milestone build page.

BIRT 2.6 Webinar

2010-07-08T13:32:00.000-07:00

Thanks to all those who attended the New BIRT 2.6 Features in Helios webinar. The recording is available on Eclipse Live. The examples used in the webinar are available at BIRT-Exchange.

BIRT 2.6 Released

2010-06-23T06:26:00.000-07:00

BIRT 2.6 is now available and with this release many improvements and new features are available. Charting with BIRT has been improved adding support for a Radar/Polar chart type, palette hash patterns, better JPG quality, and improved SVG to PDF support. Changes have been made to the designer to support better per project classpath management, multiple resource files for localization, and support for locale and collation strength sorting properties.

To read more about the new BIRT 2.6 features see the BIRT New and Notable Features.

Conditional Table Filters

2010-06-09T07:47:00.000-07:00

Just ran across this and it is a nice technique for those situations where you are limited to table based filtering of data. Typically, I focus on data filtering as far up stream as possible. It is better to filter data at the source (in the where clause for JDBC). Next, I use DataSet based filtering.

But sometimes you can't filter at the Source or the DataSet, which is where table based filtering comes in. The issue with table based filters is that there is no good way in the UI to implement conditional filtering. For instance, imagine you have a data driven parameter multi-select parameter and you want to limit the choices to the values from that parameter.

This is relatively simple to do, you just create a multi-select parameter and add a filter to a table.

So what happens if your user wants to select all of the values in the list? They need to select each of the values from the pick list that appears. Unfortunately, with large pick lists this is a little tricky for the end user. In addition, table based filtering on large pick list may create performance issues.

What you would like to do is make the parameter optional, and if the value for the parameter is not set, then just don't filter on that parameter value.

The UI does not support this type of behavior, but it is easy to do through a small amount of script on the table in the onPrepare method.

importPackage( Packages.org.eclipse.birt.report.engine.api.script.element ); 
importPackage( Packages.org.eclipse.birt.report.model.api.simpleapi ); 

if(params["Region"].value!= null){
    var filterCondition = StructureScriptAPIFactory.createFilterCondition(); 
    filterCondition.setExpr("row['COUNTRY']"); 
    filterCondition.setOperator("eq");
    filterCondition.setValue1("params[\"Region\"]");
    
    var filterKey = filterCondition.getStructure();
    var filterItem = SimpleElementFactory.getInstance().createFilterCondition( filterKey )
    this.addFilterCondition( filterItem );
}

Now how would you handle the situation if you had multiple filter conditions that you wanted to add? A trivial re-factor and you can create a general purpose method add filter method.

// generic function to add a filter to a table
function addFilterItem (table, rowExpr, paramExpr){
  
  var filterCondition = StructureScriptAPIFactory.createFilterCondition(); 
  filterCondition.setOperator("in");
  filterCondition.setExpr(rowExpr); 
  filterCondition.setValue1(paramExpr);

  // could do in one step, shows DEAPI creation steps
  var filterKey = filterCondition.getStructure();
  var filterItem = SimpleElementFactory.getInstance().createFilterCondition( filterKey );

  table.addFilterCondition(filterItem);
}

This method can then be placed into a JavaScript file, a Script extension point, or a global location. Calling the file from the table is equally easy.

// add filters dynamically
if (params["Country"].value != null )
  addFilterItem (this, 'row["COUNTRY"]' , 'params["Country"].value' );

if (params["City"].value != null)
  addFilterItem (this, 'row["CITY"]' , 'params["City"].value' );

It is important to recognize that the second and third parameters that are being passed are expressions and not values. So what is happening is we are creating a filter, and that filter will use the express row["COUNTRY"] to look up the appropriate country values. That is why you need to pass the exact expression through in the function.

If you are having trouble figuring out the appropriate expression, just build the expression that you want in the UI, and then search through the XML for the word filter. You will see the expressions in the XML. Just copy these expressions and pass them to your function. Just delete the static filter and you are all set. Yes, you can use different operators then the IN clause, but it seems the most appropriate for this type of filtering.

BIRT Excel Output

2010-06-02T12:26:00.000-07:00

BIRT 2.5.2 provides a variety of tools to construct reports to analyze data. These include charts, aggregation elements, drill to detail capabilities, nested tables, data cubes and crosstabs. These features are presented very well in the AJAX based viewer when deployed to the web, supporting pagination, table of contents, and exporting of data and contents to other formats. Out of the box, BIRT supports exporting to HTML, paginated HTML, WORD, PDF, PostScript, PPT, and Excel. BIRT also provides an extension point to implement your own emitters. For an example of implementing an XML emitter see Developing an Eclipse BIRT XML Report Rendering Extension or tBIRT: Writing an Emitter.

As stated earlier BIRT supports exporting to Excel. The BIRT Excel emitter creates a Microsoft Office XML XLS document that can be opened in Microsoft Office 2003 or greater. To use this feature either add the __format=xls parameter to the BIRT viewer URL or use the AJAX export button.

if you are using the Report Engine API, simply set up a render option for XLS.



                //RunAndRender Task
  IReportRunnable design = null;
  design = engine.openReportDesign("Reports/myreport.rptdesign"); 
  IRunAndRenderTask task = engine.createRunAndRenderTask(design);   
  EXCELRenderOption options = new EXCELRenderOption(); 
  options.setOutputFormat("xls");
  options.setOutputFileName("output/resample/myxls.xls");
  task.setRenderOption(options);
  task.run();
  task.close();

                //or Render Task
  IReportDocument document = null;
  document = engine.openReportDocument("output/resample/myreport.rptdocument"); 
  EXCELRenderOption options = new EXCELRenderOption();
  options.setOutputFormat("xls");
  options.setOutputFileName("output/resample/xlsoutput.xls");
  IRenderTask task = engine.createRenderTask(document);   
  task.setRenderOption(options);
  task.render();

While the XLS output is quite good, some features are not supported. For example new worksheets on page breaks are not created and images and charts are not exported to the XLS. While the team continues to improve the XLS emitter there are some other options for emitting XLS. One of these options is to use the Tribix emitter located on source forge. The Tribix project offers emitters for RTF, PPT and XLS.

If you wish to use just the XLS emitter, download the org.uguess.birt.report.engine.emitter.xls_version and org.uguess.birt.report.engine.common_version plugins and copy them to the plugins directory in your Eclipse install location. You will also need to copy them to the runtime location as well. For example, if you are using the WebViewer this will be the WebViewer/WEB-INF/Platform/plugins directory. You will also need to remove org.eclipse.birt.report.engine.emitter.excel.config_version and org.eclipse.birt.report.engine.emitter.prototype.excel_version plugins from both locations to replace the out of the box XLS emitters. Restart Eclipse with the –clean option and the Tribix emitter should work. No API changes should be required if you are using the RE API. New worksheets per page and image support should now work.

If you desire more XLS output options take a look at the Actuate XLS emitter that will be available in Actuate BIRT 11 which will be released this fall. It allows exporting charts as either images or as native XLS charts.

It also provides the capability to export formulas using a new scripting language called EasyScript, within the BIRT Expression Builder.

The Actuate BIRT XLS emitter also offers the capability to export BIRT Crosstabs to native XLS Pivot Tables.

If you are interested in trying out the Actuate BIRT XLS emitter take a look at the Acutate 11 Milestone download page located on BIRT-Exchange.

Adventures with Fonts

2010-05-20T12:39:00.000-07:00

One of the biggest problems facing report developers is how to efficiently support multiple languages using multiple output formats (HTML, PDF, Excel...) BIRT provides support for multiple languages but the support is both OS and output format dependent. Having gone through this process a couple of times, I have been asked to share my experiences, hopefully it will simplify the task if you run into similar issues.

What I knew going in was that fonts are handled differently depending on the type of output. HTML fonts are rendered in the users browser, PDF fonts are rendered on the server by BIRT, and chart fonts are rendered on the server by Java AWT. On top of all that, fonts in the development environment are rendered by SWT. There are different ways to configure fonts for each of these situations.

For HTML reports, the user must have the appropriate fonts installed on their machine.

For PDF reports, BIRT renders the fonts on the server using information in the various fontsConfigXXX.xml files located in plugins/org.eclipse.birt.report.engine.fonts_XXX. The base file is fontsConfig.xml and there are additional files to handle specific operating systems. There are some useful comments in fontsConfig.xml that explain how this works. I know these files are used for PDF generation and I think they are also used for rendering fonts in the development environment.

From a previous font adventure, I knew that BIRT uses AWT to render charts, so font configuration is done in the lib folder of the JRE by manipulating various properties files. Documentation on this seems to be a bit sketchy, but this site has some information.

My customer's problem, had to do with PDF output. Thai characters were displaying as question marks in their 2.2.1.1 BIRT reports. This was happening on all the OS's they ran, including Windows, Solaris and Linux. The characters looked fine in HTML output, but the PDF rendered characters incorrectly. Their system administrator stated that they had full language packs installed on all of the machines.

I started my investigations on their Windows box, running Windows Server 2003. The first thing I looked at was the fontsConfig.xml file in plugins/org.eclipse.birt.report.engine.fonts_2.2.1.v20070823. I noticed there was a block element for Thai in the commented out section:

I realized this has the rather nice effect of dynamically switching fonts in mid-string whenever characters within this range are encountered. There's no need to use a special font in the report design and that's particularly important in multi-lingual environments.

The only problem was the font family. The sample element didn't tell me what it should be and I couldn't tell by looking looking at the font files in C:\windows\fonts. I tried downloading several font viewers but none of them told me what I needed to know.

Then I had the good luck to check on my laptop, which runs Windows 7. In Windows 7, the font listing in windows explorer shows lots more information about the fonts, including a column called "Designed For". I found there were several fonts that were "designed for" Thai and Angsana New was one that also existed on their server. I used Angsana New for the font family in the block element and restarted their web application and it fixed it!

Next I had to preform this feat on their Solaris box.

Of course I tried Angsana New right off the bat, but it wasn't going to be that easy.

I started exploring the installed packages on my on Ubuntu box by searching for "font" in the synaptic package manager. I found all kinds of programs and spent a good amount of time looking at the man pages for them and trying them out, but the only one I found that told me which fonts support which character ranges was gucharmap, the Gnome version of the character map program.

The left side has a list of "Scripts" and one of them was Thai. Clicking on that showed the Thai character set (which is relatively small). I found that holding the right mouse button down over a character would display its font name. On my Ubuntu box the font was Waree, which worked for my machine but did not solve the client's issue.

Using gucharmap on the clients machine showed that their server was using AngsanaUPC. A quick modification to the fontsConfigXXX.xml to use AngsanaUPC and the problem was resolved. The main lesson I learned from this was how to find font families that support specific blocks of unicode characters.

For windows, Windows 7 explorer works nicely. I am unsure how to handle this if you are using XP. For Linux gucharmap worked, but it was dependent on the particular distro of Linux. The only downside to this approach was the need to have XWindows access. I will continue looking for a good command line utility that can be used to research installed fonts on servers. If anyone has found a utility like this, I would love to hear about it.

More on Chart Interactivity

2010-05-06T09:39:00.000-07:00

In an earlier post we examined chart interactivity with a focus on the Invoke Script Action, which allowed client side scripts to be called. This post is available here.

At the end of the post we mentioned predefined variables that are passed to the script that is invoked. These variables are:

evt – The Event Object.
categoryData – The Chart Category Value.
valueData – The Chart Orthogonal Value.
valueSeriesName – The specific Series Name.
legendItemText – The specific legend entry Text.
legendItemValue – The value of the specific legend entry.
axisLabel – The value of the specific axis label selected.

What these predefined variables contain depends on the chart type, how the chart is configured and what event is being fired. For example if you define a Bar chart with legend interactivity and do not show the legend value, all the variables will be null with the exception of the evt Object and the legendItemText variable. Generally these values will be populated like (evt object is always populated):

Series Interactivity Invoke Script – categoryData, valueData, valueSeriesName populated, the rest are null.
Legend Interactivity Invoke Script – legendItemText and legendItemValue populated, the rest are null.
Axis Interactivity Invoke Script – axisLabel populated, the rest are null.
All other Interactivity Invoke Script – All are null.

To see the values you can call an invoke script function to alert them. For example, select a specific series on a chart within the third tab of the chart wizard and select interactivity. For the event enter Mouse Click. For the Action choose invoke script and enter the following script.

ShowEventData(evt, categoryData, valueData, valueSeriesName, legendItemText, legendItemValue, axisLabel);

Next add a text element to the report that has the following value.

<script language="JavaScript">

function ShowEventData(evt, categoryData, valueData, valueSeriesName, legendItemText, legendItemValue, axisLabel) {

alert( "categoryData=" + categoryData + 
"\nvalueData=" + valueData + 
"\nvalueSeriesName=" + valueSeriesName + 
"\nlegendItemText=" + legendItemText + 
"\nlegendItemValue=" + legendItemValue + 
"\naxisLabel=" + axisLabel);
 
}
</script>

Make sure you set the type to HTML for the text element. The output when clicking on the series should look similar to:

An example report that contains this event on all interactivity elements is available at Birt-Exchange.

An example that uses the predefined variables with client side script to toggle the visibly of a chart series is also available at Birt-Exchange.

Multi-View Report Items

2010-04-22T09:26:00.000-07:00

BIRT currently supports the concept of a multi-view report item. What this means is that two report items share the same data bindings and physical space, but only one is displayed. In the current version of BIRT only tables and crosstabs support this multi-view feature and the second view must be a chart. Generally the view that is displayed is chosen at design time, but this can be altered using some script and a report parameter.

To create a multi-view report item, first create a table or crosstab. Next right click on the report item and select Create Chart View.

This will launch t he Chart Builder. Construct the chart as usual. After creating the chart a second tab will appear at the bottom of the report item.

The tab selected currently determines which view will be displayed. The selected view can also be changed with script and a report parameter. First select the table tab and name the table.

In this case I have named the table “mytable”. Next add a report parameter to use in the script. The parameter should allow two choices, show as chart or show as table. In this example I have named the report parameter ShowAs and the parameter has chartview or tableview as possible values.

Finally enter the following script in the beforeFactory event.



var th = reportContext.getDesignHandle().findElement("mytable");
var mvh = th.getProperty("multiViews");

if( params["ShowAs"].value == "chartview" ){
 mvh.setProperty("index", "0" );
}else{
 mvh.setProperty("index", "-1" );
}

The first line retrieves a handle to the table and the second retrieves a handle to the multiviews property for the table. The parameter is then used to set the index for the multiview item.

The output will look similar to:

And

This example is available at Birt-Exchange.

BIRT Roadshow Series Continues – Help decide the content!

2010-03-28T14:30:00.000-07:00

In the past year Actuate has been running free one day BIRT training events, where users are introduced to BIRT technology by a series of talks followed by some hands on training exercises. This road show series, which was conducted in major cities around the globe, has been heavily attended.

Actuate is currently planning a new series that focuses on some of the more advanced topics of BIRT and is looking for feedback on what the community would like to see in the agenda. Are you interested in learning more about Charting, Advanced Scripting, or Custom data sources? To provide input simply follow this link, which provides a form for your input. It should take less than five minutes to complete.

BIRT 2.5.2 Enhancements

2010-03-09T13:00:00.000-08:00

As BIRT 2.5.2 was released recently, I wanted to post on some of the new features available in the release. BIRT 2.5.2 represents a maintenance release, which is generally dominated with bug fixes and not new enhancements, but this release does have a few that are worth noting.

SQL Query Builder
The SQL Query Builder is now directly available without creating a connection profile. When adding a new data source, the query builder is listed as one of the data sources available.

After selecting the Query Builder data source you are prompted with a list of available databases. Once you select the type of database you can then specify the specific driver and connection properties that will be used.

One of the advantages to using this driver is that the jar location of the driver is a data source property and can be changed using Property Binding or an Event Handler Script.

<property name="jarList">C:\birt\mysql\mysql-connector-java-5.0.4-bin.jar</property>

After the data source is created, you create a dataset just like you would with any other BIRT data source. The editor allows graphic query creation as shown in the following image.

Designer Classpath Configuration

In prior releases of BIRT, the classloader while in the designer would search all projects within the workspace to locate a class that was used within the design. This would happen for classes invoked used in expressions or JavaScript event handlers. Event handlers written in Java where located in this fashion as well. In BIRT 2.5.2 you can now configure the classpath for the workspace or for the individual project that BIRT will use. To set this preference select the window->preferences->Report Design->Classpath entry.

Sorting Enhancement
BIRT provides sorting on many report items, such as tables, group sections, and crosstabs. New for BIRT 2.5.2 is ability to set the collation strength and locale for the sorter.

Crosstab Cheat Sheet and Template
A new Report Template and Cheat Sheet are available for creating a cross tab style report.

Other enhancements are also in BIRT 2.5.2 and these can be viewed in bugzilla. The full list of bug fixes is also available with this query. You can download BIRT 2.5.2 here.

BIRT and Struts 2

2010-02-22T14:04:00.000-08:00

BIRT offers several ways reports can be deployed. The AJAX based BIRT viewer can be deployed to your application server, the BIRT tag libraries can be used or you can deploy the Report Engine in your application. You can also modify any of the above options, given that the source is available for download. Several commercial options are also available. This post explains deploying the BIRT engine as an Action component within Struts2. It also discusses using Actuate’s JSAPI with Struts 2’s Bean tag.

BIRT Engine Deployed to Struts 2

The BIRT report engine can be deployed as a Servlet and the process for doing this is described in the BIRT wiki.

If you happen to be using Struts 2 as your application framework you can deploy the Report Engine as an Action component. The process for doing this is not much different than the Servlet approach described in the above link. First you have to implement the ActionSupport class.



package org.birt.struts2;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.ByteArrayOutputStream;
import java.io.ByteArrayInputStream;
import org.apache.struts2.util.ServletContextAware;
import org.apache.struts2.interceptor.ServletRequestAware; 
import javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;

import com.opensymphony.xwork2.ActionSupport;
public class BirtStruts2 extends ActionSupport implements ServletContextAware, ServletRequestAware {

 private ByteArrayInputStream inputStream;

 public ByteArrayInputStream getInputStream() {
  return inputStream;
 }
 private HttpServletRequest request;
 public void setServletRequest(HttpServletRequest request) {
  this.request = request;
 }   
 private ServletContext context;  
 public void setServletContext(ServletContext context) {  
  this.context = context;  
 }  
 public String execute() throws Exception {

  RunBirt rb = new RunBirt();
  inputStream = new ByteArrayInputStream(rb.runReport(this.context, this.request));

  return SUCCESS;
 }

}

In this example we are going to create a RunBirt class that will return the report in a byte array. The above BirtStruts2 class extends the ActionSupport class and implements ServletContextAware and ServletRequestAware. The reason we implement the two extra interfaces is that the RunBirt class will need the ServletContext and the Request object. The BirtStruts2 class also has an inputStream member that is used by the Struts 2 framework to handle the returned report. The struts.config file is as follows:

<!DOCTYPE struts PUBLIC
"-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
"http://struts.apache.org/dtds/struts-2.0.dtd">
<struts>
<package name="BirtStruts2" extends="struts-default">
<action name="BirtStruts2" class="org.birt.struts2.BirtStruts2">
<result type="stream">
<param name="contentType">text/html</param>
<param name="inputName">inputStream</param>
</result>
</action>
</package>
</struts>

The result for the BirtStruts2 action is set to stream, the content type is set to html, and the inputStream variable from our BirtStruts2 class is set as the inputName stream result parameter. You will need to change the contentType if you plan on altering the example to return PDF, XLS, or Word.

The RunBirt class is similar to the WebReport class described in the Wiki example.



public byte[] runReport(ServletContext sc, HttpServletRequest req) throws ServletException{

  this.birtReportEngine = BirtEngine.getBirtEngine(sc);
  
  IReportRunnable design;
  try
  {
   //Open report design
   design = birtReportEngine.openReportDesign( sc.getRealPath("/Reports/TopNPercent.rptdesign") );
   //create task to run and render report
   IRunAndRenderTask task = birtReportEngine.createRunAndRenderTask( design );  
   task.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, RunBirt.class.getClassLoader()); 
   //task.getAppContext().put("BIRT_VIEWER_HTTPSERVLET_REQUEST", req );   
   if( req.getParameter("TopCount") != null ){
    task.setParameterValue("Top Count", Integer.valueOf(req.getParameter("TopCount")));
   }
   if( req.getParameter("TopPercentage") != null ){
    task.setParameterValue("Top Percentage", Float.valueOf(req.getParameter("TopPercentage")));
   }
   //set output options
   HTMLRenderOption options = new HTMLRenderOption();
   options.setOutputFormat(HTMLRenderOption.OUTPUT_FORMAT_HTML);
   ByteArrayOutputStream oStream = new ByteArrayOutputStream(); 
   options.setOutputStream(oStream);
   options.setImageHandler(new HTMLServerImageHandler());
   options.setBaseImageURL(req.getContextPath()+"/images");
   options.setImageDirectory(sc.getRealPath("/images"));   
   task.setRenderOption(options);
      
   
   //run report
   task.run();
   task.close();
   return oStream.toByteArray();
   
  }catch (Exception e){
   
   e.printStackTrace();
   throw new ServletException( e );
  }
 }
}

If you have used the BIRT Report Engine API there is nothing unique in this example for Struts 2. The report name is hard-coded but could easily be changed to be set as a parameter. The HTML render options are setup to write to a ByteArrayOutputStream which is then converted to a byte array and returned the BirtStruts2 class.


HTMLRenderOption options = new HTMLRenderOption();
options.setOutputFormat(HTMLRenderOption.OUTPUT_FORMAT_HTML);
ByteArrayOutputStream oStream = new ByteArrayOutputStream(); 
options.setOutputStream(oStream);
options.setImageHandler(new HTMLServerImageHandler());
options.setBaseImageURL(req.getContextPath()+"/images");
options.setImageDirectory(sc.getRealPath("/images"));   
task.setRenderOption(options);

The images directory and base URL (pre-pended to the img src tag in the output) are also set based on the passed in ServletContext and Request objects. The only other class is the BirtEngine class which is desribed in the Wiki example but is shown here for completeness. This class provides static synchronized method to return the ReportEngine.



package org.birt.struts2;
import javax.servlet.ServletContext;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.eclipse.birt.report.engine.api.EngineConstants;
import org.eclipse.birt.report.engine.api.HTMLRenderOption;
import org.eclipse.birt.report.engine.api.IReportRunnable;
import org.eclipse.birt.report.engine.api.IRunAndRenderTask;
import org.eclipse.birt.report.engine.api.IReportEngine;
import org.eclipse.birt.report.engine.api.HTMLServerImageHandler;
import org.eclipse.birt.report.engine.api.PDFRenderOption;
import org.eclipse.birt.report.engine.api.RenderOption;
import java.io.ByteArrayOutputStream;

public class RunBirt{
private IReportEngine birtReportEngine = null;

package org.birt.struts2;

import java.io.InputStream;
import java.io.IOException;
import java.util.Properties;
import java.util.logging.Level;

import org.eclipse.birt.report.engine.api.EngineConfig;
import org.eclipse.birt.report.engine.api.IReportEngine;
import javax.servlet.*;
import org.eclipse.birt.core.framework.PlatformServletContext;
import org.eclipse.birt.core.framework.IPlatformContext;
import org.eclipse.birt.core.framework.Platform;
import org.eclipse.birt.core.exception.BirtException;
import org.eclipse.birt.report.engine.api.IReportEngineFactory;
import org.eclipse.birt.report.engine.api.ReportEngine;
import javax.servlet.http.HttpServletRequest;

public class BirtEngine {

 private static IReportEngine birtEngine = null;

 private static Properties configProps = new Properties();

 private final static String configFile = "BirtConfig.properties";

 public static synchronized void initBirtConfig() {
  loadEngineProps();
 }

 public static synchronized IReportEngine getBirtEngine(ServletContext sc) {
  if (birtEngine == null) 
  {
   EngineConfig config = new EngineConfig();
   if( configProps != null){
    String logLevel = configProps.getProperty("logLevel");
    Level level = Level.OFF;
    if ("SEVERE".equalsIgnoreCase(logLevel)) 
    {
     level = Level.SEVERE;
    } else if ("WARNING".equalsIgnoreCase(logLevel))
    {
     level = Level.WARNING;
    } else if ("INFO".equalsIgnoreCase(logLevel)) 
    {
     level = Level.INFO;
    } else if ("CONFIG".equalsIgnoreCase(logLevel))
    {
     level = Level.CONFIG;
    } else if ("FINE".equalsIgnoreCase(logLevel)) 
    {
     level = Level.FINE;
    } else if ("FINER".equalsIgnoreCase(logLevel)) 
    {
     level = Level.FINER;
    } else if ("FINEST".equalsIgnoreCase(logLevel)) 
    {
     level = Level.FINEST;
    } else if ("OFF".equalsIgnoreCase(logLevel)) 
    {
     level = Level.OFF;
    }

    config.setLogConfig(configProps.getProperty("logDirectory"), level);
   }
config.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, BirtEngine.class.getClassLoader());
   config.setEngineHome("");
   
   IPlatformContext context = new PlatformServletContext( sc );
   config.setPlatformContext( context );
   
   try
   {
    Platform.startup( config );
   }
   catch ( BirtException e )
   {
    e.printStackTrace( );
   }

   IReportEngineFactory factory = (IReportEngineFactory) Platform
   .createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );
   birtEngine = factory.createReportEngine( config );


  }
  return birtEngine;
 }

 public static synchronized void destroyBirtEngine() {
  if (birtEngine == null) {
   return;
  }  
  birtEngine.destroy();
  Platform.shutdown();
  birtEngine = null;
 }

To call this code you can implement a page similar to the following:

<html>
<head>
</head>
<body>
<s:form action="/BirtStruts2.action" method="POST">
<s:textfield name="TopCount" label="Top Count"/><br>
<s:textfield name="TopPercentage" label="Top Percentage"/><br>
<s:submit value="Run Report" align="center"/>
</s:form>
</body>
</html>

This example has very little error checking for brevity. Also note that the report engine should be shutdown using a context listener, but should not be shutdown while the context is up and running as starting the engine is resource intensive. Finally no code is provided in the example to remove image files that are generated by the engine in the images directory.

The complete example with ant build and a readme that describes where to put the BIRT plugins and libs is available at Birt-Exchange.

Example Output:

Using Actuate’s JSAPI with Struts 2
If you are using Actuate’s JSAPI, integration with Struts 2 is very easy as the API is AJAX based and can be included in virtually any front-end. One interesting way the two technologies can be deployed together is to use the Struts 2 Bean tag to pass parameters to the JSAPI. For example assume we have the following bean class.



package com.actuate.jsapi.struts2;

public class MyRegionBean  {

 private String region;
 private String rep;

 public String getRegion(){
  //expecting rep passed in and region lookup in db
  //based on the rep.  Hard coded for example purposes
  this.region = "EMEA";
  return region;
 }
 public void setRegion(String nRegion ){
  this.region = nRegion;
 }
 public String getRep(){
  return rep;
 }
 public void setRep(String nRep ){
  this.rep = nRep;
 }
}

This bean can be used in conjunction with the JSAPI to pass report parameters to the Report Engine.

<%@ taglib prefix="s" uri="/struts-tags" %>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>JSAPI Struts 2</title>
</head>
<body>

<div id="acviewer" />
<div id="jsapi_example_container">
<script type="text/javascript"
src="http://localhost:8080/ActuateJavaComponent/jsapi">
</script>

<script type="text/javascript">
actuate.load("viewer");
actuate.initialize("http://localhost:8080/ActuateJavaComponent/",
null,
null,
null,
initViewer);
var viewer;
function initViewer()
{
viewer = new actuate.Viewer("acviewer");
var viewerwidth = 800;
var viewerheight = 620;
viewer.setWidth(viewerwidth);
viewer.setHeight(viewerheight);
runInitial();
}
function runInitial()
{
<s:bean name="com.actuate.jsapi.struts2.MyRegionBean">
<s:param name="rep" value="John Smith" />
viewer.setParameters({"Territory":"<s:property value="region" />"});
</s:bean>
viewer.setReportName("/Public/BIRT and BIRT Report Studio Examples/Sales by Territory.rptdesign");
viewer.submit();

}
</script>
</div>

</body>
</html>

In the runInitial JavaScript function the viewer components setParameters method is called passing the value of the bean’s region member variable as the value for the Territory report parameter.

More information is available on the JSAPI here.

The example is available at Birt-Exchange.

Output for this example is as follows:

BIRT Controls and Functions - Update

2010-02-18T14:27:00.000-08:00

We have updated the BIRT Functions and BIRT Controls libraries today to support versions 2.3.2 and 2.5.1. Turns out that there were some minor changes that needed to be addressed. In addition, we did a bit of work to make the naming and version numbering more consistent.

The biggest question I faced was how to do the version numbering for these plugins. As they stand, they are sub components to BIRT, which as a very specific version scheme. We thought about using version numbers that did not track BIRT versions at all. But then I started writing the documentation.

If you are using BIRT 2.3.2 then you should use 1.0.1 of the BIRT Controls...

Started to feel more like "you put your left foot in, ...". I think that there is a lot of value in making developers write the documentation. When you write your own docs, you quickly figure out when things that you have come to accept are really more difficult then they should be.

Rather than write a bunch of hokey pokey build instructions, we decided to generate the components one more time using version numbers that will be easy for the component consumers. So it may not follow the Eclipse version number guidelines, but it is easy for our clients.

And easy for our clients is my number one goal.
BIRT Controls and BIRT Functions version guidelines.
If you are using BIRT 2.3.2, then use version 2.3.2.X of our components.
If you are using BIRT 2.5.1, then use version 2.5.1.X of our components.

Also along the easy = good theme. I wanted to share how much I enjoy working with Google Code. I know that the Eclipse foundation is talking about doing some form of easy to use Eclipse Foundry type site, but in the absence of details on what is going on there, I went with Google. It has been very easy to create a project, with all the trappings a small project needs.

Home Page check
Wiki check
Issue Tracking check
Version Control (SVN or Hg) check
Downloads check
Update Site check (right out of the the SVN repository)
Administration and Security check

Makes me wonder if the foundation really needs to create our own infrastructure to manage a foundry. Perhaps there is a way to leverage an existing code foundry and focus on creating a great migration path from the foundry to the Eclipse infrastructure.

The other thing that I really love are the market places that I can use to get the word out about these controls. As a small company, we don't have a huge marketing staff (any marketing). So having not one but two great outlets that help us get the word out about our component is super helpful. Thanks again to

Enough rambling, I have to go write some docs...

BIRT Crosstab scripting

2010-02-11T11:09:00.000-08:00

BIRT supplies scripting hooks for just about every report element in the palette. You can generally implement an onPrepare, onCreate, and onRender event handler for each of these report items. The onPrepare event fires before data is retrieved and allows you to change the design for a specific report item. The onCreate event fires when the report item is being created by the report engine’s generation task. The onRender event fires when the report item is being rendered by the report engine’s render task. These events and example are described on the BIRT website.

Some report items offer more event hooks. For example a chart item actually has over thirty event hooks that allow total customization of the chart generation and presentation phases. As a side note, all chart scripts fire during the report engine’s render task. This does not mean the database is hit at render time though. The report engine will cache the data for a chart in memory or in a report document, depending on what task type is being used to run and render the report.

The BIRT crosstab element offers onPrepare, onCreate and onRender hooks as well. These events are fired both for the crosstab as a whole and for each individual cell in the crosstab. When firing events for cells, these are processed top to bottom and left to right. Handlers can be written using the script tab at the bottom of the report design view. BIRT also supplies an event adapter to allow you to write these events in Java as well.

As an example script, you can modify the crosstab in the onPrepare like:



function onPrepareCrosstab( crosstab, reportContext )
{
 var coldim = crosstab.getColumnLevels().get(0);
 coldim.removeAllFilterConditions(); 
 crosstab.getStyle().setFontFamily("Arial");
 crosstab.getStyle().setFontSize("8");
 
}

This script removes filters from the first column level and sets some font information. Some of the more interesting capabilities are available when using the onCreateCell event hook. For example consider the following script.



function onCreateCell( cellInst, reportContext )
{

 //Can reference cells by type or id - valid types "header" or "aggregation"
 if(  cellInst.getCellType() == "header" ) {
  //Get data values see binding tab on crosstab
  //if( cellInst.getDataValue("PRODUCTLINE") == "Planes" ){
  if( reportContext.evaluate("dimension['ProductGroup']['PRODUCTLINE']") == "Planes" ){
   cellInst.getStyle().setBackgroundColor("#FF0000");
   cellInst.getStyle().setFontSize("12");
  }else{
   //Set the rest to yellow
   cellInst.getStyle().setBackgroundColor("#FFFF00");
   cellInst.getStyle().setFontSize("12");
  }

 }
 //refer to crosstab header
 if( cellInst.getCellID() == 167){
  cellInst.getStyle().setBackgroundColor("Orange");
 } 
 if( cellInst.getCellType() == "aggregation"){
  //Can refernce value using getDataValue or 
  if( cellInst.getDataValue("PRODUCTLINE") == "Planes" ){
   //set color to bluegray
   cellInst.getStyle().setBackgroundColor("RGB(169,170,226)");
  }
  //by using reportContext.evaluate
  //if( reportContext.evaluate("measure['amount']") > 50000 ){
  if( cellInst.getDataValue("amount_DateGroup/quarter_ProductGroup/PRODUCTLINE") > 50000 ){
   cellInst.getStyle().setBackgroundColor("Green");
   cellInst.getStyle().setColor("White");
  }
 } 
}

The onCreateCell script is passed the reportContext and an instance of the cell. The cellInst object has several methods that can be used to determine which cell is currently being processed. You can call getCellType() which will return header or aggregation. In the following image all cells in the red box will return aggregation and all others will return header.

You can also call getCellID() which will return the specific element id that your crosstab uses for that cell.

In this example the getCellID call will return 160 every time this cell is created. This can be useful when you are trying to determine if you have a new row or column in your crosstab. If this is the innermost header element then this cell will be created for every new row/column. The only drawback to this approach is that if the crosstab is in a library or you copy and paste it, the cell ids will change.

Once you know the cell you are currently processing you generally want to access the data, to make some script decision. To do this you have a couple of choices. You can call the getDataValue method on the cell instance or use the reportContext.evaluate method. When using the getDataValue method, the value you need to refer to is the data binding column name set on the crosstab item. For example:


cellInst.getDataValue("PRODUCTLINE") == "Planes"

refers to the PRODUCTLINE data binding. Also note that this is the value of the column as this particular cell is being processed.

You can also use the reportContext.evaluate method, which allows you to build an expression and bypass the binding. For example:


if( reportContext.evaluate("dimension['ProductGroup']['PRODUCTLINE']") == "Planes" )

Essentially returns the same value as the previous getDataValue(“PRODUCTLINE”) method. This is because the PRODUCTLINE data binding has:


dimension['ProductGroup']['PRODUCTLINE']

As it’s expression. This example references a particular dimension of the cube. You can reference cube measures as well.


reportContext.evaluate("measure['amount']")

As with the column binding this will return the value for the specific cell you are currently processing.

In the script posted at the top of this post, we use the cell instance object to set specific styling based on the values of various column bindings. This is done using the getStyle method.


cellInst.getStyle().setBackgroundColor("Green");
cellInst.getStyle().setColor("White");

Using this method is no different than other BIRT report items.

Using these methods and the reportContext you can write some very sophisticated scripts. For example you can store all the quantities ordered where the product line is ships to a global variable using a script similar to this:



 if( cellInst.getCellType() == "aggregation" && cellInst.getCellID() == 151){
  if( cellInst.getDataValue("PRODUCTLINE") == "Ships" ){
   importPackage(Packages.java.lang );
   var cur = cellInst.getDataValue("amount_DateGroup/quarter_ProductGroup/PRODUCTLINE");
   if( reportContext.getGlobalVariable("totalplanes")==null){
    reportContext.setGlobalVariable("totalplanes", new Double(Double.parseDouble(cur)) );   
   }else{
    var oldcnt = reportContext.getGlobalVariable("totalplanes");
    reportContext.setGlobalVariable("totalplanes", new Double(Double.parseDouble(oldcnt) + Double.parseDouble(cur)));  
   }
  }
 }

This value can then be referenced within the same crosstab or later in the report. For example the following expression for a text item can be used.

<VALUE-OF format="#,##0.00">reportContext.getGlobalVariable("totalplanes");</VALUE-OF>

This example can also be implemented in Java. In the attached link the report will contain two crosstabs. One where the code is done in JavaScript and the other uses an event handler written in Java, which is also attached.

The example report output is presented below.

The examples are available at Birt-Exchange.

Remus Uses BIRT

2010-02-02T14:49:00.000-08:00

I read about the Remus project on Planet Eclipse today and was intrigued. Looking at the draft project proposal:

With today's information technologies, the amount of information we consume daily is enormous. Efficient management and fast access to frequently used information has become more important than ever. The fact that we use a wide range of applications and digital mediums makes the aggregation of information, search and retrieval even more difficult. Managing a huge amount of information successfully requires an intelligent tool that enables users to file, categorize and visualize such diverse types of data as information units in a single application.

And now I am very intrigued, my company Innovent Solutions works in this very space. Naturally, I wondered about how BIRT could interact with Remus. Turns out that they have created an ODA for BIRT and have bundled some reports.

Looks like another nice use of BIRT.

BIRT 2.5 Integration Webinar

2010-01-28T10:48:00.000-08:00

For those who attended the Webinar we did this week, I am attaching the slides and examples. They are available at BIRT Exchange. If you did not get a chance to participate, the recording is available at Eclipse Live. The examples illustrate different deployment and use cases and were built using BIRT 2.5.

Thanks Lynn for putting this together.

Using Actuate’s JSAPI with a JBoss SEAM component

2010-01-15T09:29:00.000-08:00

If you are using Actuate’s JSAPI to run BIRT reports and you wish to pass parameters from a SEAM component this can be done very easily. In addition you can combine SEAM remoting with the JSAPI to do some interesting things. For example assume we create a SEAM component that retrieves report parameters that we want to use with the JSAPI. The component would look similar to this:



package com.actuate.seam.example;

import org.jboss.seam.annotations.*;
import org.jboss.seam.*;
import org.jboss.seam.annotations.remoting.WebRemote;

@Name("reportParameters")
@Scope(ScopeType.SESSION)
public class ReportParameters {
    private String parmName = "";
    private String parmValue = "";
    public String getParmName() {
        return parmName;
    }
    public void setParmName(String pn) {
        this.parmName = pn;
    }
    public String getParmValue() {
        return parmValue;
    }
    public void setParmValue(String pv) {
        this.parmValue = pv;
    } 
    @Create
    public void initData() {
  setParmName("customer");
  setParmValue("CAF Imports");
    }
 @WebRemote
 public String getAlternateReport() {
      return "/Public/BIRT and BIRT Report Studio Examples/Top 5 Sales Performers.rptdesign";
 }           
}

All we have in this class is a report parameter name and value. Obviously the values would not be hard coded but for simplicity they are in this example. We also have one web remote method to retrieve the path of a specific report. We will use this to change the report being rendered via SEAM remoting. The XHTML page would look like the following:



<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
 xmlns:ui="http://java.sun.com/jsf/facelets"
 xmlns:h="http://java.sun.com/jsf/html"
 xmlns:s="http://jboss.com/products/seam/taglib">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Seam Remoting - Actuate JSAPI Example</title>
</head>

<body>
<h1>Seam Remoting -Actuate JSAPI Example</h1>
<p></p>
<s:remote include="reportParameters" />

<button onclick="javascript:changeReport()">Change Report</button>
<div id="acviewer" />
<div id="jsapi_example_container">
<script type="text/javascript"
 src="http://localhost:8080/ActuateJavaComponent/jsapi">
</script>

<script type="text/javascript">
  actuate.load("viewer");
  actuate.initialize("http://localhost:8080/ActuateJavaComponent/",
  null,
  null,
  null,
  initViewer);
  var viewer;
  function initViewer()
  {
   viewer = new actuate.Viewer("acviewer");
   var viewerwidth = 800;
   var viewerheight = 620; 
   viewer.setWidth(viewerwidth);
   viewer.setHeight(viewerheight);
   runInitial();
  }
  function runAlternate(newReport)
  {
   viewer.setReportName(newReport);
   viewer.submit();
  }
  function runInitial()
  { 
   viewer.setParameters({"#{reportParameters.parmName}":"#{reportParameters.parmValue}"});
   viewer.setReportName("/Public/BIRT and BIRT Report Studio Examples/Customer Order History.rptdesign");
   viewer.submit();
  }
     function changeReport() {
         var callback = function(newReport) { runAlternate(newReport); };
        Seam.Component.getInstance("reportParameters").getAlternateReport(callback);
     }
</script>
</div>
</body>
</html>

We use the standard JSAPI viewer tag to run the report, with the EL-Bindings to retrieve the report parameter name and value when the page is loaded. The page also has a button to change the report. This button uses SEAM remoting to call the getAlternateReport method which returns the path to the new report. The callback function then calls the runAlternate JavaScript method which in turn calls the JSAPI to run the new report. When the page is first loaded the following is displayed.

Notice that the report is executed for CAF Imports, which is the parameter retrieved from the ReportParameters class. Clicking on the change report button will display the following.

This example is based on the SEAM remoting helloworld example. It was tested with JBoss AS 5.1.0 and SEAM 2.2.0. The source for it is available here. To run this example download and extract it to the jboss-seam-2.2.0.GA\examples\remoting directory. If you have already set the application server settings in the SEAM build.properties file, all you should have to do to build the example is type:
Ant explode in the example directory.

If you have downloaded Actuate’s Java Component technology and wish to deploy it to JBoss 5.1.0 GA, you will need to extract the war and remove xercesImpl.jar from the ActuateJavaComponent/WEB-INF/lib directory. Rebuild the WAR and deploy to your JBoss AS.

Quick and Dirty Logging

2010-01-13T12:02:00.000-08:00

One of the best ways to debug your BIRT Expressions and JavaScript is logging. I have worked with a number of different techniques for logging, and finally settled on using the script functions to create a logging utility. This approach can be seen in the birt-functions-lib project.

But I frequently don't have the functions library, and I just want examine a value or an object. I need quick and dirty logging, not a logging infrastructure.

As you probably know, BIRT JavaScript can interact with Java objects natively. So I should be able to invoke

java.lang.System.out.println("message");

and see an output message. There are just two tiny 'tricks' you need to know about to make this work.

First, the Eclipse application that BIRT runs under has a console mode. To run eclipse in console mode run eclipsec.exe instead of eclipse.exe.

Second, in order to access the java.lang package you need to preface your method call with the keyword Packages, as in:

Packages.java.lang.System.out.println("message");

As you can see, your message will appear in the console window, quick and dirty.

If you are going to be doing a lot of quick and dirty logging, you can use the importPackage method to clean things up:

importPackage(Packages.java.lang);
System.out.println("message with import package");

You can even create a global function that will wrap off the message generation if you are feeling motivated.

importPackage(Packages.java.lang);
function log(msg){
    System.out.println(msg);
}
reportContext.setGlobalVariable("log", log);

log("Test global function");

But my feeling is that once you have reached that level, it would be just easier to use a script function and allow people to select the function through the UI. Did I mention that there is an open source functions library that will do this for you?

EclipseCon Submissions - Last Chance to Propose a Talk

2009-12-18T08:45:00.000-08:00

Oisín Hurley is one of the smartest, funniest and best looking people in the Eclipse community* So when he says jump, I jump.

That's right it is the last day to get your EclipseCon submission for a talk in. If you have been doing anything interesting with BIRT that you would like to share with the Eclipse community, we would love to hear about it. There are lots of opportunities to present at different lengths.

Head on over to the EclipseCon submission site and make a proposal about how you are using BIRT.

*And totally immune to blatant attempts at flattery.

BIRT Plugins at Google Code

2009-12-14T10:18:00.000-08:00

Blackboard, Inc. develops solutions for the K-12 school, college campus, workplace, and community that increase the impact of education by transforming the experience of education. Blackboard has chosen BIRT as its reporting and business intelligence tool.

Over the last two years I have been lucky to work with Blackboard on their BIRT integration. Working with their product and developers we have been able to enhance their core product with reports. Each Blackboard report tells a story that can help their clients better perform their jobs.

One of BIRT's features that was extremely helpful was the ability to customize and extend BIRT to meet Blackboards requirements. Using the BIRT extension points we added functions and controls to BIRT that improved both the developer and users experience when interacting with BIRT.

Blackboard has agreed to release some of the generic portions of this work back to the BIRT community as open source contributions. Rather than rolling these contributions into the core product (where it would quickly get lost amidst all the other code) we have created two small open source projects that can be used by the community. These projects can be used either as fully functional products or as best practice sample code.

	BIRT Functions	Uses the Aggregate and Script Function extension point to add new functions to the BIRT product.
	BIRT Controls	Uses the ReportItem extension point to create new elements that show up on BIRT reports.
	Innovent Update Site	Hosts an Eclipse Update site for both projects. We will be adding new projects to this site as we finish up the code.

If you are a BIRT developer that just wants to get started you can use the following update link:
http://innovent.googlecode.com/svn/trunk/update

If you would like to find out a bit more about the projects, please visit the project sites.

Thanks go out to thank both BIRT Exchange and the brand spanking new Eclipse Marketplace for providing access to our projects. It is really great to have a couple of quality channels to publicize our work to the BIRT community.

Also, I want to mention the team that helped to build and get this code open sourced. Steve Schafer from Innovent Solutions wrote a lot of the code and figured out the inner workings of the ReportItem exension point. Blackboard had a whole team of people working on reports, in particular thanks to Heather, JoAnna, Michelle, Dan, Joe, Joel, and Manpreet.

Calling Client Side JavaScript from a BIRT Chart

2009-12-11T17:07:00.000-08:00

A couple of months ago I detailed a new feature for BIRT charts that allows multiple hyperlinks to be attached to one the supported events. That post is available here.

In this post I will discuss using a BIRT Text element that contains script which executes within the client browser and contains functions that are called from rendered charts.

General Information
BIRT currently supports interactivity on many chart components like chart series, title, axis, and the legend. The components that support interactivity will depend on the type of chart being used. The events are client based events like mouse click, mouse over, key down, etc. Multiple events can be hooked and each is associated with an action. Actions define the behavior that should occur when a specific event happens. The actions available depend on what component the action is defined for and what chart output type is being used. Currently BIRT supports the following Actions.

Hyperlink – Supports multiple hyperlinks, drill through, and linking to bookmarks.
Show Toolip – Supports displaying tooltips. Data available for use in the tooltip will depend on the component.
Highlight – Highlights the selected component. Most often used to highlight specific series or data point.
Toggle Visibility – Toggles the visibility of the selected component. Most often used to change the visibility of a series or data point.
Toggle DataPoint Visibility – Toggles the data point label visibility.
Invoke Script – Invokes client side script.

Additionally if you are using the Chart engine within an SWT, SVG, or Swing based application the engine supports adding a callback action that your code can use to interpret chart events.

Highlight, Toggle Visibility, and Toggle DataPoint Visibility actions are only available when using an SVG output setting.

If you use SVG, and you wish to test the report in the designer remember to set the Enable SVG chart in the Preview preferences for the Report Design Preference entry.

More information on Chart Interactivity is available here. Also see the Chart FAQ for more details.

InvokeScript Example
The follow section details an example of using the invokeScript action on multiple Chart events.

Assume that you have a Chart that displays a set of customers with a series value for each equal to the customer's credit limit.

Suppose you want to display the customer details right below the chart when the mouse is moved over a specific data point. This can be done using the invokeScript action on the mouse over event for the chart series. To do this first create a table below the chart that is bound to the same dataset that the chart is using. You can then nest a table that calls another data set to retrieve customer information. In the attached example this will be the ChartData and CustomerInformation datasets respectively.

By default this will generate a inner table that contains customer information for every customer represented in the chart. Obviously you do not want to display all of these at once, so create a new style in the style editor with only one property overridden – Text Block:Display set to no Display. Apply this new style to both the inner and outer tables.

If you run the report after completing this step all the tables will be generated in the output but none will be displayed. This is different than using the visibility property which will not put the tables in the output. Enter the following bookmarks for the outer and inner tables.

Outer table bookmark expression: "myoutertable";
Inner table bookmark expression: "mytable"+row["CUSTOMERNUMBER"]

This will assign the outer table id to myoutertable and a unique id for each inner table starting with mytable and the customer number for the given inner table appended to it. We can now use these with some client script to turn them on or off.

Add a Text element below the two tables with the following value.


<script>
function clearSel(){
   var ot=document.getElementById("myoutertable");
   ot.style.display="none";
   var intbls=ot.getElementsByTagName("TABLE");
   for( jj=0; jj<intbls.length; jj++ ){
    intbls[jj].style.display = "none";
   }
}
function DisplayCustomer(cat) {
 clearSel();
 //alert(cat);
 document.getElementById("myoutertable").style.display="block"
 document.getElementById("mytable"+cat).style.display="block"
 
}
</script>

Make sure to set the Text type to HTML.

The clearSel function first finds the outer table and then locates every nested table and sets the display style for each to none. The outer table’s display style is also set to none. This will effectively hide both tables.

The DisplayCustomer function first clears all current displayed tables. Next it uses a category passed in from the Chart to find the specific customer inner table and sets its display style to block. It also sets the outer table to be visible.

To link these two functions to the Chart use the Interactivity button on the Value (Y) Series as shown in the picture below. Note that we use a mouse over event to call the DisplayCustomer function and a mouse click function to clear the tables.

This produces the following output.

As the mouse is moved over the different tubes the table below the chart will update. To clear the tables click on one of the tubes. You will notice that we passed categoryData to the DisplayCustomer JavaScript function. This is a predefined variable available to the invokeScript function that contains the category value for a specific datapoint. The example report lists the predefined variables and in what action they are available using label elements at the top of the report. These labels are hidden at run time.

The example is available at BIRT Exchange.

BIRT Designer Classpath Changes

2009-12-01T14:01:00.000-08:00

Starting with the 2.5.2 branch of BIRT (Release date February 2010), configuring the classpath for the designer has been improved. This classpath setting is used by the BIRT engine when processing reports that use Java event handlers or make calls to external classes while in the designer. In previous releases of BIRT, the engine would add all Java projects within the same workspace to the classpath automatically. With BIRT 2.5.2 you will now be able configure the BIRT classpath globally or project specific. This setting is available in the preferences.

In this example I have configured a project (BIRT Reports) to add the BirtEventHandlers Java project to the classpath that the BIRT engine uses when previewing the reports in the designer. Note these changes only affect the designer and you should deploy your event handler classes to the scriptlib directory in the deployed environment. More details are available in the bugzilla entry.

Accessing Spring Beans from the BIRT Designer

2009-11-20T16:00:00.000-08:00

Recently I have described methods that can be used to access Spring Beans from the BIRT Engine. These examples are intended to be illustrative and not comprehensive.

More on BIRT and Spring

Calling Spring Objects from BIRT Expressions and Event Handlers

In both of these examples I used the BIRT engine to retrieve Spring objects within the scripting environment. In this post I am supplying an example that illustrates how to implement your own menu in the expression builder, so Spring objects can be called within the BIRT Designer. This will allow you to test your report prior to deployment.

In this post:
BIRT 2.3.1 - Adding Functions to the Expression Builder
I described how to implement the org.eclipse.birt.core.ScriptFunctionService. The attached example is an implementation of this extension point. When using this example the expression builder will appear as follows.

Notice that there is now a SpringFunctions sub-category, which provides one method callBean. This method takes a bean name and a method name and expects a returned string. To keep the example simple no arguments are supported and the method must return a string. The plugin.xml looks like the following:

Provided with the example is a deployable J2EE application and the plugin that implements the ScriptFunctionService. See the readme for details on setting up the example. Also note that the deployable plugin is also attached in the example. You will need to add this to your designer and your runtime. This example works with both the Open Source BIRT designer and the Actuate BIRT designer.

Also included is an example report with the following output.

This example is available at Birt-Exchange.

It's Movember

2009-11-13T20:13:00.000-08:00

Movember, that time of year when the days grow shorter, the weather grows colder and the family gathers today for the holidays. Of course in my family the kids are looking at me and laughing, and I am getting 'that' look from Gretchen my wife.

Yes I am growing in a mustache in an effort to change the face of men's health. To quote my team lead (I am a part of Team Fat Cyclist).

"Movember is the month formerly known as November. During this month, men — manly men — grow mos as a way to call attention to themselves (hey, I’m just being honest here).

Then, when people ask you “Why are you growing a moustache?” — and they will ask you this question — you tell them about the cancers affecting men, and ask them to donate to your Mo donation page (the money will be channeled to the Prostate Cancer Foundation and to LiveStrong).

So really, a mo is kinda like wearing a pink ribbon for breast cancer awareness. But a lot more personal. And harder to remove. And it’s displayed a lot higher."

-The Fat Cyclist (Elden Nelson)

If you are interested in supporting me and helping to raise money for men's health issues, please visit my mo page and donate.

If not me, please visit another great team, the Eclipse Momitters.

More on BIRT and Spring

2009-11-12T11:23:00.000-08:00

In my previous post I discussed calling Spring objects within a BIRT report. That example used an architecture similar to the simplified diagram below.

The Spring Context was injected in the BIRT app context and this gave the BIRT scripting environment access to the Spring Beans. This example could have been expanded further to the Open Source BIRT Viewer by adding a similar object to the Application Context for the BIRT Viewer. See this wiki page for more details. If you use the method described in the wiki page, you may prefer to implement this with a Spring RequestContextFilter.

The simplified architecture for this setup is presented below.

Another option is to use Spring Remoting and the Open Source BIRT Viewer tag libraries or standard URL integration. In this case you add the Spring jars to the WEB-INF/lib of the viewer and write a wrapper class for the Spring remote client. The wrapper class and Spring configuration file can then be added to the WEB-INF/lib directory of the Viewer to access your remote beans. The architecture for this setup would be as follows. Attached to this post is an example of this method.

If you are using the Actuate Java Components technology, you can use the JSAPI within a standard HTML page or generate it in a Spring View which will include the BIRT report. This approach allows Flash charts to be populated by Spring Beans and report interactivity like dynamically grouping, sorting and filtering all without re-executing the report.

The example, that is attached to this post, is a very simple Spring Remoting example. It contains two ANT projects, one for the server application and one that acts as the remote client wrapper. Once you download the example, build the server application and deploy it. Instructions are in a readme file. Then build the client wrapper jar and deploy it as described in the readme. The readme illustrates deploying to the Open Source BIRT Viewer or the Actuate Interactive Viewer. The example uses Spring HTTP Remoting, but any of the Spring Remoting technologies should work. An example report is provided for both deployed environments. Whether you are using the Open Source BIRT Report designer or the Actuate BIRT Designer, the expression to access the Spring Bean will be similar to the following.

Output for the example is as follows.

Open Source Viewer

Actuate Interactive Viewer

The Example is available at BIRT Exchange.

Calling Spring Objects from BIRT Expressions and Event Handlers

2009-11-05T07:38:00.000-08:00

Several examples are already available on the web, which demonstrate calling the BIRT engine from a Spring MVC application.

Integrating BIRT with Spring in a Web application
and
Eclipse BIRT in Spring web applications
are a couple of examples.

There is not much information on how to include Spring Beans within a report design. This post details an example of injecting the Spring ApplicationContext into BIRT’s AppContext object which will allow you to call your Spring Beans in BIRT expressions or event handlers. A link for the source is listed at the bottom. A readme file containing instructions for building the example is included in the download.

You can include the BIRT runtime by following the post above or examining the download. The Example implements a Spring Controller with the following code.


package org.eclipse.birt.spring;

import javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.eclipse.birt.report.engine.api.HTMLRenderOption;
import org.eclipse.birt.report.engine.api.HTMLServerImageHandler;
import org.eclipse.birt.report.engine.api.IReportEngine;
import org.eclipse.birt.report.engine.api.IReportRunnable;
import org.eclipse.birt.report.engine.api.IRunAndRenderTask;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.servlet.mvc.AbstractController;

public class BirtController extends AbstractController {

  private IReportEngine reportEngine;

  protected ModelAndView handleRequestInternal(HttpServletRequest request, HttpServletResponse response) throws Exception {

 String reportName = request.getParameter("ReportName");
 ServletContext sc = request.getSession().getServletContext();
 reportEngine = BirtEngine.getBirtEngine(sc);
 IReportRunnable runnable = null;
 runnable = reportEngine.openReportDesign( sc.getRealPath("/Reports")+"/"+reportName );
    IRunAndRenderTask runAndRenderTask = reportEngine.createRunAndRenderTask(runnable);

    HTMLRenderOption options = new HTMLRenderOption();
    options.setOutputFormat("html");
    options.setOutputStream(response.getOutputStream());
 options.setImageHandler(new HTMLServerImageHandler());
 options.setBaseImageURL(request.getContextPath()+"/images");
 options.setImageDirectory(sc.getRealPath("/images"));
    runAndRenderTask.setRenderOption(options);
    runAndRenderTask.run();

    return null;
  }

}

Note that no error checking is implemented in this example. This controller class just extends the Spring AbstractController class passes the response object to the BIRT engine to output the report. The report name is retrieved from the request. Before running the report the BirtEngine class is used to retrieve the BIRT engine. This is virtually the same BirtEngine class used in the servlet example available in the BIRT wiki with some exceptions that are noted here.


package org.eclipse.birt.spring;

import java.io.InputStream;
import java.io.IOException;
import java.util.Properties;
import java.util.logging.Level;

import org.eclipse.birt.report.engine.api.EngineConfig;
import org.eclipse.birt.report.engine.api.IReportEngine;
import javax.servlet.*;
import org.eclipse.birt.core.framework.PlatformServletContext;
import org.eclipse.birt.core.framework.IPlatformContext;
import org.eclipse.birt.core.framework.Platform;
import org.eclipse.birt.core.exception.BirtException;
import org.eclipse.birt.report.engine.api.IReportEngineFactory;
import org.springframework.context.ApplicationContext; 

public class BirtEngine {

 private static IReportEngine birtEngine = null;

 private static Properties configProps = new Properties();

 private final static String configFile = "BirtConfig.properties";

 public static synchronized void initBirtConfig() {
  loadEngineProps();
 }
 public static synchronized IReportEngine getBirtEngine(ServletContext sc) {
  if (birtEngine == null) 
  {
   //optionally load engine props
   //loadEngineProps();
   EngineConfig config = new EngineConfig();
   if( configProps != null){
    String logLevel = configProps.getProperty("logLevel");
    Level level = Level.OFF;
    if ("SEVERE".equalsIgnoreCase(logLevel)) 
    {
     level = Level.SEVERE;
    } else if ("WARNING".equalsIgnoreCase(logLevel))
    {
     level = Level.WARNING;
    } else if ("INFO".equalsIgnoreCase(logLevel)) 
    {
     level = Level.INFO;
    } else if ("CONFIG".equalsIgnoreCase(logLevel))
    {
     level = Level.CONFIG;
    } else if ("FINE".equalsIgnoreCase(logLevel)) 
    {
     level = Level.FINE;
    } else if ("FINER".equalsIgnoreCase(logLevel)) 
    {
     level = Level.FINER;
    } else if ("FINEST".equalsIgnoreCase(logLevel)) 
    {
     level = Level.FINEST;
    } else if ("OFF".equalsIgnoreCase(logLevel)) 
    {
     level = Level.OFF;
    }

    config.setLogConfig(configProps.getProperty("logDirectory"), level);
   }
   config.setEngineHome("");
   
   IPlatformContext context = new PlatformServletContext( sc );
   config.setPlatformContext( context );
   config.getAppContext().put("PARENT_CLASSLOADER", BirtEngine.class.getClassLoader());
   ApplicationContext sprCtx = ContextAccess.getApplicationContext();
   config.getAppContext().put("spring",sprCtx);   
   try
   {
    Platform.startup( config );
   }
   catch ( BirtException e )
   {
    e.printStackTrace( );
   }

   IReportEngineFactory factory = (IReportEngineFactory) Platform
   .createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );
   birtEngine = factory.createReportEngine( config );
  }
  return birtEngine;
 }
 public static synchronized void destroyBirtEngine() {
  if (birtEngine == null) {
   return;
  }  
  birtEngine.destroy();
  Platform.shutdown();
  birtEngine = null;
 }
 public Object clone() throws CloneNotSupportedException {
  throw new CloneNotSupportedException();
 }
 private static void loadEngineProps() {
  try {
   //Config File must be in classpath
   ClassLoader cl = Thread.currentThread ().getContextClassLoader();
   InputStream in = null;
   in = cl.getResourceAsStream (configFile);
   configProps.load(in);
   in.close();
  } catch (IOException e) {
   e.printStackTrace();
  }
 }
}

This class just wraps access to the BIRT engine in a singleton.
The notable changes are in these lines of code deal with the EngineConfig class.


   config.setEngineHome("");
   
   IPlatformContext context = new PlatformServletContext( sc );
   config.setPlatformContext( context );
   config.getAppContext().put("PARENT_CLASSLOADER", BirtEngine.class.getClassLoader());
   ApplicationContext sprCtx = ContextAccess.getApplicationContext();
   config.getAppContext().put("spring",sprCtx);

The setEngineHome is passed a blank value and setting the PlatformContext to use a PlatformServletContext class will by default look for the BIRT plugins in the WEB-INF/Platform/plugins directory. Next we set the parent classloader for the report engine plugin so that classes available to the project will also be available to the BIRT engine. The final line gets the Spring ApplicationContext instance and loads it into the BIRT AppContext object and names it “spring”. The method used for retrieving the Spring context is described in a great post here.

The ContextAccess class is defined as follows.


package org.eclipse.birt.spring;
import org.springframework.context.ApplicationContext; 
public class ContextAccess {
 private static ApplicationContext ctx;
 public static void setApplicationContext(ApplicationContext applicationContext) {   
  ctx = applicationContext;   
 }
 public static ApplicationContext getApplicationContext() {
  return ctx;
 }
}

This Class just contains methods to set and get the static variable ctx, which will contain the Spring ApplicationContext with the addition of one more class.



package org.eclipse.birt.spring;

import org.springframework.beans.BeansException;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ApplicationContextAware; 


public class SpringContextProvider implements ApplicationContextAware {
 public void setApplicationContext(ApplicationContext ctx) throws BeansException {
  ContextAccess.setApplicationContext(ctx);
 }
}

This Class implements the ApplicationContextAware interface which causes the Spring framework to callback this class with the Spring context, when it is created. The Spring configuration file for this example looks like the following.

<beans>
<bean id="springContextProvider" class="org.eclipse.birt.spring.SpringContextProvider">
</bean>
<bean id="urlMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
<property name="mappings">
<props>
<prop key="/runbirt.htm">birtController</prop>
</props>
</property>
</bean>
<bean id="birtEngine"
class="org.eclipse.birt.spring.BirtEngine"
destroy-method="destroyBirtEngine">
</bean>
<bean id="birtController"
class="org.eclipse.birt.spring.BirtController">
</bean>
<bean id="carPojo"
class="org.eclipse.birt.spring.CarPojo">
</bean>

</beans>

We have a carPojo bean that is available. To access this from a BIRT expression, all we have to do is use the following syntax.


var mypojo = spring.getBean("carPojo");

You can then call the methods on the object. Eg mypojo.getYear();

Output for the example is presented below.

Caveats
If you preview the report in the designer the report will not work. This is because the Spring context is not available to the designer. The report has to be deployed to test it. There are many ways this example could be extended to circumvent this issue. BIRT provides an extension point to enhance the expression builder which could be used with Spring Remoting to access the Spring context. BIRT also provides an extension to implement a BIRT application context object within the designer that could be used in this same fashion. I will try to implement one of these methods in the future to illustrate this concept.

The example can be downloaded from Birt-Exchange.

Multiple Hyperlinks on BIRT Charts

2009-10-20T11:51:00.000-07:00

BIRT 2.5.1 was released a couple of weeks ago and with its release BIRT Charts now support multiple hyperlinks. To use this feature select any of the interactivity locations within the chart builder. Next select the add button under the hyperlinks list box.

This will launch the hyperlink editor.

Enter the name you wish to appear in the context menu. Next select the edit base URL button, which will display the Hyperlink Options editor.

Here you have the option to link to a URI, a bookmark within the same report or to a bookmark in another report. Values from the current chart can be passed through to the target. For example the value of a slice could be passed to a google query. To do this select the URI radial and enter an expression similar to the one shown in the image below.

When running the report containing the chart, the multiple hyperlinks menu will popup on whatever event you defined in the editor. In the above example this was defined on a mouse click event. So clicking on a slice of the pie will cause the multiple hyperlinks context menu to appear.

This sample report is available at Birt-Exchange.

Calling BIRT reports from Wicket using Actuate’s JSAPI

2009-09-28T18:47:00.000-07:00

I have written several posts on how to use the Actuate JSAPI to integrate with various frameworks. In this post I will detail integrating with Wicket. For more information on the JSAPI see this post:

Showing BIRT Reports using the Actuate JSAPI

Wicket can call BIRT reports with the JSAPI in a similar fashion as other front end frameworks that allow AJAX based APIs, where JavaScript is just embedded into the HTML. An HTML file based on the Hello World Wicket example may look similar to the following.

<html>
<head>
<title>Actuate JSAPI Wicket Example</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Viewer creation example</title>
</head>
<body>
<b>
<span wicket:id="message">message will be here</span>
</b>

<div id="acviewer" />

<div id="jsapi_example_container"><script type="text/javascript"
src="http://localhost:8080/ActuateJavaComponent/jsapi"></script> <script
type="text/javascript" language="JavaScript">

actuate.load("viewer");
actuate.initialize("http://localhost:8080/ActuateJavaComponent/",
null,
null,
null,
initViewer);
var viewer;
function initViewer()
{
viewer = new actuate.Viewer("acviewer");
var viewerwidth = 800;
var viewerheight = 620;
viewer.setWidth(viewerwidth);
viewer.setHeight(viewerheight);
run();
}
Using a Wicket Behavior to write out this code
function run()
{
viewer.setParameters({"Customer":"CAF Imports"});
viewer.setReportName("/Public/BIRT and BIRT Report Studio Examples/Customer Order History.rptdesign");
viewer.submit();
}

</script></div>
</body>
</html>

This example will look very familiar to other examples in the JSAPI overview post. The only real difference is the addition of the wicket message, which is generated by my instance of the Wicket Web Page class. You will notice that the run JavaScript function is hard coding the report name and parameters. This may be something you want to handle in the Java code, to make it more dynamic. One way of handling this is to use Wicket Behaviors to create custom components. You could use a Behavior to write out all the above JavaScript, but we will keep it simple and just write out the run script. So the first thing to do is to create a class that extends the AbstractBehavior class.


package jsapi.wicket.sample;

import org.apache.wicket.Component;
import org.apache.wicket.Response;
import org.apache.wicket.behavior.AbstractBehavior;
import org.apache.wicket.util.string.JavascriptUtils;

public class ReportComponent extends AbstractBehavior{

 private static final long serialVersionUID = 1L;

 public void onRendered(Component component) {
        Response response = component.getResponse(); 
        response.write(JavascriptUtils.SCRIPT_OPEN_TAG);
        response.write("function run(){");
        response.write("viewer.setParameters({\"Customer\":\"CAF Imports\"});");
        response.write("viewer.setReportName(\"/Public/BIRT and BIRT Report Studio Examples/Customer Order History.rptdesign\");");
     response.write("viewer.submit();}");
        response.write(JavascriptUtils.SCRIPT_CLOSE_TAG);
    }

}

This class overides the onRendered method to write out the entire run script from the HTML above. I can now modify my extended WebPage class to add an instance of the ReportComponent class.


package jsapi.wicket.sample;

import org.apache.wicket.PageParameters;
import org.apache.wicket.markup.html.WebPage;
import org.apache.wicket.markup.html.basic.Label;

public class ReportParameter extends WebPage {

 private static final long serialVersionUID = 1L;

 public ReportParameter(final PageParameters parameters) {

  // Add the simplest type of label
  Label myLabel = new Label("message", "Actuate JSAPI Wicket Example");
  add(myLabel);
  ReportComponent rc = new ReportComponent();
  myLabel.add(rc);
 }
}

The script is written below the Label component.
Finally the HTML should have the run JavaScript function commented out. The output from this example is as follows.

The generated HTML looks like:

Note that you can use the built in view time functions like selecting new parameters and rerunning the report without any additional code.

The example files can be downloaded from Birt-Exchange.

Calling BIRT reports from Flex using Actuate’s JSAPI

2009-09-03T11:43:00.000-07:00

Continuing on a series of posts I have written around Acuate’s JSAPI, this post details integrating BIRT reports with Flex. Previous posts detailed:

Showing BIRT Reports using the Actuate JSAPI
See this link for more details on what is available in the JSAPI.

Calling BIRT Reports from PHP using Actuate’s JSAPI

Calling BIRT Reports from ASP.NET using Actuate’s JSAPI

BIRT Reports can contain Flash components using the Text element. Actuate has also extended the BIRT report designer to include Flash charts. As stated in previous post the JSAPI can be used to include BIRT content in just about any front end. BIRT currently does not support a Flash emitter, but a Flex component can call the JSAPI to include and modify BIRT content within the same HTML page. This post details how this can be achieved.

The Flex SDK provides a Flex Ajax bridge that allows a Flex application to call and interact with Ajax based APIs. To illustrate how this can be used with Actuate’s JSAPI, I am going to build a Flex application that list a couple of reports. The application will also contain a button to execute the report. The output for the report will be written to another DIV element within the HTML wrapper.

The mxml file is pretty simple and contains a DataGrid that calls an action script to load the names and paths of two reports.


<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
   width="640" height="300" layout="vertical"  backgroundColor="white">
   <fab:FABridge xmlns:fab="bridge.*" />
   
   <mx:Panel id="pnlMain" x="10" y="10" width="560" height="260" 
   layout="absolute" title="BIRT Reports From Flex">
  <mx:DataGrid id="dgReports" x="10" y="10" initialize="initReports()" width="530" height="130">
    <mx:columns>
      <mx:DataGridColumn headerText="Report Name" width="160" dataField="name"/>
      <mx:DataGridColumn headerText="Report Path" dataField="path"/>
    </mx:columns>
  </mx:DataGrid>
  <mx:Button x="10" y="156" label="Run Report From Flex" id="flashButton" />
</mx:Panel>  
<mx:Script>
 <![CDATA[
   import mx.collections.ArrayCollection;
   
   public function initReports():void
   {
     var reports:Array = new Array();
     reports.push({name: "Monthly Revenue Analysis", path: "/Public/BIRT and BIRT Report Studio Examples/Monthly Revenue Analysis.rptdesign"});
     reports.push({name: "Sales by Territory", path: "/Public/BIRT and BIRT Report Studio Examples/Sales by Territory.rptdesign"});
     var reportCollection:ArrayCollection = new ArrayCollection(reports);
     dgReports.dataProvider = reportCollection;
     dgReports.selectedIndex = 0;
   }
 ]]>
</mx:Script>
</mx:Application>

The fab:FABridge xmlns:fab=”bridge.*” tag includes the Flex Ajax bridge library. In this example I just added a bridge directory to my application, which contained the FABridge.as and FABridge.js files that handle the bridge. These files are available in the Flex SDK. This application also contains a button (flashButton) that will be used by JavaScript later in the example.

My wrapper HTML file contains a div element to display the application which is named BirtFlex. The flashvars parameter is used to set a unique bridge name for this application. The bridge name is used by JavaScript to get/set values within the Flex application.


  <div id="fply">
  <script language='javascript' charset='utf-8'>
   document.write("<object id='flexApp' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' codebase='http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=8,5,0,0' type='application/x-shockwave-flash' height='300' width='640'>");
   document.write("<param name='flashvars' value='bridgeName=birtexample'/>");
   document.write("<param name='src' value='BirtFlex.swf'/>");
   document.write("<embed name='BirtFlexDemo' pluginspage='http://www.macromedia.com/go/getflashplayer' src='BirtFlex.swf' height='300' width='640' flashvars='bridgeName=birtexample'/>");
   document.write("</object>");
  </script>
  </div>

For brevity, I have foregone error checking and player checks.
To use the JSAPI the following code is added to the wrapper HTML file.


  <div id="jsapi_example_container">
   <script type="text/javascript" src="http://localhost:8080/ActuateJavaComponent/jsapi"></script>
   <script type="text/javascript" language="JavaScript">

    actuate.load("viewer");
    actuate.initialize("http://localhost:8080/ActuateJavaComponent/",
         null,
         null,
         null,
         initViewer);
    var viewer;
    function initViewer()
    {
     document.getElementById("run").disabled = true;
     viewer = new actuate.Viewer("acviewer");
     var viewerwidth = 500;
     var viewerheight = 620;     
     viewer.setWidth(viewerwidth);
     viewer.setHeight(viewerheight);
     setupFlashCallBack();
    }
    function run()
    { 
     var flexApp = FABridge.birtexample.root();
     var appValue = flexApp.getDgReports().getSelectedItem().path;
     viewer.setReportName(appValue);
     viewer.submit();
    }
    function setupFlashCallBack()
    {
     var initCallback = function()
     {
      //alert("Enabling");
      document.getElementById("run").disabled = false;
     }
     var btnCallback = function()
     {
      var flexApp = FABridge.birtexample.root();
      flexApp.getFlashButton().addEventListener("click",flashButtonClicked);
     }
     FABridge.addInitializationCallback("birtexample",initCallback);
     FABridge.addInitializationCallback("birtexample",btnCallback);
    }    
    function flashButtonClicked(event)
    {
     run();
    }
   </script>
  </div>

This code is very similar to previous examples with a few notable exceptions. When the JSAPI is initialized the call back function initViewer is set.


 actuate.initialize("http://localhost:8080/ActuateJavaComponent/",
         null,
         null,
         null,
         initViewer);

Once the API is initialized, the initViewer JavaScript function is called.


    function initViewer()
    {
     document.getElementById("run").disabled = true;
     viewer = new actuate.Viewer("acviewer");
     var viewerwidth = 500;
     var viewerheight = 620;     
     viewer.setWidth(viewerwidth);
     viewer.setHeight(viewerheight);
     setupFlashCallBack();
    }

In addition to a button in the Flex application, the HTML wrapper also contains one to run the report. Not that two buttons are needed, but for illustrative purposes, this example contains two. In this example we disable the button until both the JSAPI and the Flex component are initialized. The Viewer JSAPI component is created as usual and then the setupFlashCallBack() function is called.


    function setupFlashCallBack()
    {
     var initCallback = function()
     {
      document.getElementById("run").disabled = false;
     }
     var btnCallback = function()
     {
      var flexApp = FABridge.birtexample.root();
      flexApp.getFlashButton().addEventListener("click",flashButtonClicked);
     }
     FABridge.addInitializationCallback("birtexample",initCallback);
     FABridge.addInitializationCallback("birtexample",btnCallback);
    }

In this function two call back functions are registered. The first one (initCallback) is setup to let us know when the Flex application is loaded, which then enables the run button. The second one (btnCallback) registers an event handler that the bridge will call when the Flex button is pressed. This event handler JavaScript function simply calls the run JavaScript function.


    function flashButtonClicked(event)
    {
     run();
    }

The JavaScript button has the run function setup on the onclick event.


 <input type="button" id="run" value="Run Report From JavaScript" onclick="run()" >

So the report can be run from either button. The run function sets the report name and executes the API to run the report.


    function run()
    { 
     var flexApp = FABridge.birtexample.root();
     var appValue = flexApp.getDgReports().getSelectedItem().path;
     viewer.setReportName(appValue);
     viewer.submit();
    }

The report path is retrieved using the getDgReports().getSelectedItem().path command. The DataGrid in the mxml file is named dgReports


<mx:DataGrid id="dgReports" x="10" y="10" initialize="initReports()" width="530" height="130">

The bridge provides getter and setter methods for the items in the Flex application. The DataGrid contains two columns (name and path). The path contains the location of the report, so this is the field that is retrieved from the Flex application. See the Flex developers guide for more details on the bridge calls.

This example can be downloaded at Birt-Exchange.

Using Script to Modify a BIRT Chart

2009-08-26T13:23:00.000-07:00

When designing BIRT reports that contain charts, the developer has many ways a chart can be customized. One way is to implement a script event handler either in JavaScript or Java. The chart engine currently supports over thirty hooks for implementing an event handler. These events are fired during the generation and rendering of the chart. Many items can be customized. For example, the data for a chart can be changed in the afterDatasetFilled script, or the entire chart model can be changed in the beforeGeneration script.

In addition to changing the chart using the chart scripting hooks, the chart model can also be changed using the primary BIRT report script hooks. When making changes to the report, most developers will use the beforeFactory event script. This event is fired prior to running the report and offers a location to make simple or complex changes to the report. This includes modifying any charts that exist within the report. Simple chart properties can be changed using the Chart Simple API. An example of this approach is described here.

For more complex changes, the Chart API can be called within the script. As an example, changing a specific chart series type is possible. BIRT 2.5 provides study charts which allow multiple Y-axes to be stacked, each with a different series type. Turning this feature on or off can also be done using script. These two changes can be done with the following script:

First import the API packages that will be needed.


 importPackage(Packages.org.eclipse.birt.chart.model.data.impl);
 importPackage(Packages.org.eclipse.birt.chart.model.type.impl);
 importPackage(Packages.org.eclipse.birt.chart.model.attribute.impl);

Retrieve the report design handle and find the chart. Note that the chart needs to be named. This can be done in the general properties for the chart.


 //Chart must be named
 cht = reportContext.getDesignHandle().findElement("MyChart");
 //get the chart model;
 mychart = cht.getReportItem().getProperty( "chart.instance" );

Next retrieve the axes. In this example the chart has two Y-Axes. The second one contains the series to be modified.


  xAxis =mychart.getAxes().get(0);
  yAxis2 = xAxis.getAssociatedAxes().get(1);

Clear all series definitions defined for the second Y-axis.


 yAxis2.getSeriesDefinitions().clear();

The example report contains a combo parameter that allows the user to select the series type for the second Y-Axis. The parameter is checked and an appropriate series is created. Note that if an area series is created, the background is set to translucent.


 if( params["SeriesType"].value == "Line"){
  var ns = LineSeriesImpl.create();
 }else if( params["SeriesType"].value == "Bar"){
  var ns = BarSeriesImpl.create();
 }else if( params["SeriesType"].value == "Area"){
  var ns = AreaSeriesImpl.create();
  ns.setTranslucent(true);
  ns.getLineAttributes().setColor(ColorDefinitionImpl.TRANSPARENT())


 }

Create a new series definition and set the appropriate query and series type.


 var sdNew = SeriesDefinitionImpl.create();
  sdNew.getSeriesPalette( ).shift( 0 );
 ns.getLabel().setVisible(true);
 var qry = QueryImpl.create("row[\"QUANTITYORDERED\"]" );
 ns.getDataDefinition().add(qry)
 sdNew.getSeries().add( ns );

Assign the new series definition to the second Y-Axis.


 yAxis2.getSeriesDefinitions().add( sdNew );

The example report also has a Boolean parameter that determines if the chart should be displayed as a study chart.



 if( params["StudyChart"].value == true ){
  mychart.setStudyLayout(true);
 }else{
  mychart.setStudyLayout(false);
 }

Some of the output options for this example report are displayed below.

This report is available at Birt-Exchange.

Calling BIRT reports from PHP using Actuate’s JSAPI

2009-08-13T14:30:00.000-07:00

I have written a couple of post on using Actuate’s JSAPI to include BIRT content within your system. This API is AJAX based and allows content to be embedded within most web applications.

These post can read here:
Calling BIRT Reports from ASP.NET
and
Actuate's JSAPI

In addition take a look at calling the BIRT Engine from PHP, which I blogged about a while back.

Calling the JSAPI from PHP is not much different than any other front end. For example, including the interactive viewer can be done using the following code.


<?php
$JSAPI_Location='http://localhost:8080/ActuateJavaComponent/jsapi';
$ReportFile='/Public/BIRT and BIRT Report Studio Examples/Customer Dashboard.rptdesign';
?>
<HTML>
 <head>
 </head>
 <body>

  <div id="jsapi_example_container">
   <script type="text/javascript" src="<?php echo $JSAPI_Location ?>"></script>
   <script type="text/javascript" language="JavaScript">
    <!-- Load the viewer component of the Actuate object -->
    actuate.load("viewer");    
    actuate.initialize("<?php echo substr($JSAPI_Location, 0, -5) ?>",
         null,
         null,
         null,
         initViewer);
    var viewer;
    function initViewer()
    {
     viewer = new actuate.Viewer("acviewer");
     <!-- register an event handler to catch exceptions -->     
     viewer.registerEventHandler(actuate.viewer.EventConstants.ON_EXCEPTION, errorHandler);
     run();
    }
    function run()
    { 

     viewer.setReportName("<?php echo $ReportFile ?>");
     viewer.submit();
    }
    function errorHandler(viewInstance, exception)
    {
     alert(exception.getMessage());
    }
   </script>
   <div id="acviewer"></div>
  </div>
 </body>
</HTML>

In this example I am setting the JSAPI location and report file to run using a couple of PHP variables. The JSAPI is initialized and the callback function initViewer is called which creates the viewer within the acviewer div element. The initViewer function then calls the run method which sets the report to run and executes it. The report is then displayed within the acviewer div element.

If the report has parameters you can use the parameter component of the JSAPI or set them using PHP variables.

Change the code above to add the parameter values.


<?PHP
$JSAPI_Location='http://localhost:8080/ActuateJavaComponent/jsapi';
$ReportFile='/Public/BIRT and BIRT Report Studio Examples/Sales By Territory.rptdesign';
$reportTerritory='NA';
$reportYear=2004;
?>

Next, within the run method set the parameters using code similar to the following.


    function run()
    { 
                     viewer.setParameters(
                                  {
"Territory": "<?php echo $reportTerritory ?>",
"currentYear": <?php echo $reportYear ?>
                                  }
                     );
     viewer.setReportName("<?php echo $ReportFile ?>");
     viewer.submit();
    }

To use the parameter component use code similar to the following.


<html>
<body>
<?php
 $JSAPI_Location='http://localhost:8080/ActuateJavaComponent/jsapi';
 $ReportFile='/Public/BIRT and BIRT Report Studio Examples/DateTest.rptdesign'; 
?>


 <div id="jsapi_example_container">
  <script type="text/javascript" src="<?php echo $JSAPI_Location ?>"></script>
  <script type="text/javascript" language="JavaScript">
   var paramObj;
   var viewer;
   actuate.load("viewer");
   actuate.initialize("<?php echo substr($JSAPI_Location, 0, -5) ?>",
            null,
            null,
            null,
            init);

   function init()
   {
    <!-- parameter -->
    paramObj = new actuate.Parameter("parampane");
    <!-- register an event handler to catch exceptions -->
    paramObj.registerEventHandler(actuate.parameter.EventConstants.ON_EXCEPTION, parameterErrorHandler);
    <!-- viewer -->
    viewer = new actuate.Viewer("viewerpane");
    var viewerwidth = 800;
    var viewerheight = 600;
    <!-- register an event handler to catch exceptions -->
    viewer.registerEventHandler(actuate.viewer.EventConstants.ON_EXCEPTION, errorHandler);    
    viewer.setWidth(viewerwidth);
    viewer.setHeight(viewerheight);
    runParam();
   }
   
   function runParam()
   {
    paramObj.setReportName("<?php echo $ReportFile ?>");
    paramObj.submit(function () {document.getElementById("run").style.visibility = 'visible';});   
   }

   function run()
   {
    paramObj.downloadParameterValues(runNext);
   }

   function runNext( pvs )
   {
    viewer.setParameterValues(pvs);
    viewer.setReportName("<?php echo $ReportFile ?>");
    viewer.submit();
   }
   
   function errorHandler(viewInstance, exception)
   {
    alert(exception.getMessage());
   }
   
   function parameterErrorHandler(exception)
   {
    alert(exception.getMessage());
   }
   
  </script>
   <table border=1>
    <tr> 
     <td><div id="parampane"></div></td>
     <td><input type="button" class="btn" id="run" value="Run Report" onclick="run()" style="visibility: hidden"></td>
    </tr>
   </table>
   <div id="viewerpane"></div>
  </div>
</body>
</html>

The run function downloads the parameters that were set using the parameter component. Next the setParameterValues method is used to set the parameter values for the run of the report. Notice this example has a date parameter, and the JSAPI provides a date picker for this type of parameter.

If you are already using some PHP class to implement a date picker, such as the one available at the Zebra PHP Components Framework blog, you can modify your code to retrieve the date from the id of the element the date is stored in. The above example would have the following modifications:


<?php
    // include the class
    require "class.datepicker.php";
    // instantiate the object
    $dp=new datepicker();
 $dp->dateFormat="m/d/Y";
 $JSAPI_Location='http://localhost:8080/ActuateJavaComponent/jsapi';
 $ReportFile='/Public/BIRT and BIRT Report Studio Examples/DateTest.rptdesign'; 
?>

   function runNext( pvs )
   {
    //viewer.setParameterValues(pvs);
    viewer.setParameters({"currentYear":2003, "currentMonth":12, "DateParameter":document.getElementById("date").value});    
    viewer.setReportName("");
    viewer.submit();
   }


   <table border=1>
    <tr>
     <td><input type="text" id="date"></td>
     <td><input type="button" value="Select Date" onclick="<?=$dp->show("date")?>"></td>
    </tr>
    <tr>
     <td><div id="parampane"></div></td>
     <td><input type="button" class="btn" id="run" value="Run Report" onclick="run()" style="visibility: hidden"></td>
    </tr>
   </table>
   <div id="viewerpane"></div>

The Heavy Hand

2009-07-09T09:49:00.000-07:00

Today I received a foundation email with this little nugget in it:

Pursuant to the Eclipse Foundation Bylaws, the Eclipse Foundation recently amended the Eclipse Foundation Bylaws and Membership Agreement. As required by the Eclipse Foundation Membership Agreement, we require your formal acceptance of these changes which became effective July 23, 2008 and are more fully described at: http://www.eclipse.org/membership/vote2008/.

Formal acceptance is required by virtue of the Membership Agreement. It should be noted that these changes are not optional and apply to all Eclipse Members upon Membership renewal from July 23, 2008 onwards. (emphasis added)

Now I have no problem with the changes to the by laws. In fact, they are great for my small company. What I don't understand is why I need to agree in writing to these non-optional requirements?

If the decision has all ready been made, why do I need to agree in writing? Maybe it is just me, but it feels heavy handed (and pointless) to insist that I validate a decision after it has all ready been made.

After all, if I don't like the decision I can just choose not to renew.

Passing JDBC ResultSet to a report

2009-06-26T09:54:00.001-07:00

Nice article on how to pass a JDBC resultset to a report at

Techie.Ocean

Calling BIRT reports from ASP.NET using Actuate’s JSAPI

2009-06-12T13:30:00.000-07:00

A while back I wrote a blog entry about Actuate’s new JSAPI. This API is AJAX based and allows BIRT reports to be displayed using virtually any front end. The previous post points to an article on Birt-Exchange that describes the capabilities of the API.

To include the API within an ASP.NET page is very simple. All that is needed is to add a script tag within the head tag and point it to the location you have installed the Actuate Java Component package.

<head runat="server">
<script type="text/javascript" language="JavaScript" src="http://localhost:8080/ActuateJavaComponent/jsapi"></script>
</head>

The viewer can now be created within any div statement in the page by using code similar to the following.

<div id="viewer1" style="width: 800px; height: 600px; border-width: 1px; border-style: solid;">
<script type="text/javascript" language="JavaScript">
function createViewer() {
var viewer1 = new actuate.Viewer("viewer1");
viewer1.setReportName("/Public/BIRT and BIRT Report Studio Examples/" + "<%=DropDownList1.Text%>");
viewer1.setWidth(600);
viewer1.setHeight(450);
viewer1.submit();

}
actuate.load("viewer");
actuate.initialize("http://localhost:8080/ActuateJavaComponent/", null, null, null, createViewer);
</script</div>

In the above example we are setting the report name based on a drop down list that is populated with the following code.

<asp:DropDownList ID="DropDownList2" runat="server" AutoPostBack="True">
<asp:ListItem>Customer Order History.rptdesign</asp:ListItem>
<asp:ListItem>Sales by Territory.rptdesign</asp:ListItem>
<asp:ListItem>Customer Dashboard.rptdesign</asp:ListItem>
</asp:DropDownList>

The viewer is created within the “viewer1” div tag.

The API also supplies a component for presenting parameters. This component can be created in a similar method to the viewer component.

function createParameter() {
myParam = new actuate.Parameter("myDivContainer");
myParam.setReportName("/Public/BIRT and BIRT Report Studio Examples/Sales By Territory.rptdesign");
myParam.submit();
}

This will present a parameter page that is based on the parameter designs within the report. The Parameter component can be used in conjunction with the Viewer component to display both the parameters and the report within one page.

<button onclick="runReport()">
Run Report
</button>

<div id="myDivContainer" style="border-width: 1px; border-style: solid;">
</div>
<div id="myViewerDivContainer" style="border-width: 1px; border-style: solid;">
</div>

<script type="text/javascript" language="JavaScript">
var myViewer = null;
var myParam = null;
function createParameter() {
myParam = new actuate.Parameter("myDivContainer");
myParam.setReportName("/Public/BIRT and BIRT Report Studio Examples/Sales By Territory.rptdesign");
myParam.submit();
}

function runReport() {
myViewer = new actuate.Viewer("myViewerDivContainer");
myViewer.setReportName("/Public/BIRT and BIRT Report Studio Examples/Sales By Territory.rptdesign");
myViewer.setParameters(myParam.getParameterMap();
myViewer.submit();
}
actuate.load("parameter");
actuate.load("viewer");
actuate.initialize("http://localhost:8080/ActuateJavaComponent/", null, null, null, createParameter);
</script>

This line:
myViewer.setParameters(myParam.getParameterMap();

Sets the parameters entered in the parameter component to the viewer component. If you decide to create your own parameter controls, the values can be passed to viewer component using name value pairs.

<form id="form1" runat="server">
<asp:DropDownList ID="DropDownList1" runat="server">
<asp:ListItem>NA</asp:ListItem>
<asp:ListItem>Japan</asp:ListItem>
<asp:ListItem>EMEA</asp:ListItem>
</asp:DropDownList>
</form>
.
.
myViewer.setParameters({ "Territory": document.getElementById("DropDownList1").value });

The examples are available here.

Change Page Layout

2009-05-27T09:15:00.000-07:00

Been busy writing reports lately, but I thought that I would try to publish a few quick tips that I have turned up.

One of the issues I have faced is that when a report is being formatted for PDF layout, I want it to be constrained to the page dimensions and to have it in portrait style. At the same time, when it is displayed for HTML, I want to have it in Landscape mode since the rendering seems to be better for HTML.

This little section of script placed in the beforeFactory method of the ReportItem will do that for you.

var renderO = reportContext.getRenderOption().getOutputFormat();
// change layout
if (renderO == "pdf"){
    reportContext.getDesignHandle().getMasterPages().get(0).setProperty("orientation","portrait");
} else if (renderO == "html")
    reportContext.getDesignHandle().getMasterPages().get(0).setProperty("orientation","landscape");

BIRT 2.5 M7 New and Notable

2009-05-18T07:36:00.000-07:00

BIRT 2.5 M7 was released earlier this month. This milestone adds features like, default parameter value scripting, the ability to paste HTML and RTF directly into a Text element, and independent Locale formatting. Crosstabs have also been improved to support dragging attributes directly from the data cube into the crosstab, independent visibility for a measure and its totals, and improved support for empty values associated with a time dimension. In addition a new interface is provided that allows your Java programs to track the progress of a BIRT report.

To read more about the new features, go here. As always we appreciate feedback on the new features.

BIRT Cascaded Parameters

2009-04-30T14:30:00.000-07:00

BIRT provides the capability to use dynamic parameters to present the end user with a list of choices that are populated from a dataset. This is very useful but can cause issues when the dataset returns many rows of data. To reduce the number of items in any parameter, the developer can use a cascaded parameter, which allows multiple levels and multiple datasets. When the user selects the first level parameter in a cascaded parameter group the second level in the group is automatically re-queried.

For example, if you have a customer detail report that allows the end user to select a particular customer, you could create a dynamic parameter that retrieves all the customer names from your database. The user would then select the one they are interested in, and a detail report would be generated on the selected customer. If you have thousands of customers this task becomes more difficult for the end user to navigate. To remedy this, you could create a cascaded parameter that has as its first level, the country and once that value is selected, all customers for the specific country would be listed. This assumes you have a field like country to that can be used to reduce the number of entries. If you do not have a field like this, it may be possible to create your own using script.

If we take the customer list example, one way to reduce the number of items in any of the parameter list box, would be to sort the first level of the cascade alphabetically. So the first level of the cascade could be tied to a scripted datasource that returns the letters of the alphabet. Another option is to do a distinct query on the customers within the database that retrieves only the first letter like:

select distinct SUBSTR( CUSTOMERNAME, 1, 1)
from customers

The second level in the cascade would then be defined with the following query.

select customername
from customers
where customername like ?

The question mark represents a data set input parameter, which is not the same as a report parameter. The dataset parameter can be linked to a report parameter or set programmatically using script. In this example we need to use script to add a wildcard to the query. So in the beforeOpen script of the second level query, we could do this:

inputParams["alpha"] = params["FirstLetter"]+"%";

In this example, alpha is the dataset parameter and the FirstLetter is the first level report parameter in the cascade group. In this case we are only adding the wildcard to the query.

The resultant parameter entry screen would look like:

This report is available here. Another example using a scripted data source is available here.

Multi-Select Parameters - Part 2

2009-04-14T12:58:00.001-07:00

In a previous post I described how you could create a simple method to use multi-select parameters with a SQL IN clause in a generic fashion. In that post I referenced that the right way to do this is to use Java Bind variables

There is a way that this can be done using Java Bind variables, but it is significantly more difficult.

But I did not explain how that is done. Today I gave a webinar on how you can use the Design Engine API and the BIRT Script Function extension point to dynamically add parameter binding to your report designs.

The DEAPI code is a bit tricky to use, but thanks to the ScriptFunction extension, any one can use the function quickly and easily.

All of the code and the slides for the project are available on the Innovent Subversion server here. You can use the subclipse plugin to download this code as an Eclipse project.

The slides for the presentation are included here:

BIRT Multi Select Parameters

Publish at Scribd or explore others: How-to-Guides & Manu multiselect script function

BIRT 2.5 M6 New and Notable

2009-04-01T10:28:00.000-07:00

Just wanted to drop a note to say the new and notable for BIRT 2.5 M6 is now available. Some great features are making their way into BIRT 2.5, like z ordering for combination charts, improved 508 compliance, project configuration changes, and better image marker support.

To read more about the new features, go here. As always we appreciate feedback on the new features.