Expressions make up a bulk of the scripting used in BIRT. In fact, we have used Expressions multiple times already in this book. Expressions are usually single line statements that return a single result. Tasks such as retrieving a value from a row and outputing it in a data element, retrieving parameter values, and the Highlight expressions used in the last chapter are all examples of Expressions. Any time we use the Expression editor in BIRT, we are working with Expressions.

Let's take a look at the most commonly used Expression—the Data element. Open up the Customer Orders report that we've used in the last chapter. Here we have a finished report with numerous Expressions used throughout. Let's take a look at what one of these Expressions look like.

This preceding screenshot shows us a very simple expression that retrieves the value of the CUSTOMERNUMBER column from the current row. It is taken from the Data element in the Orders detail table. dataSetRow is an array that represents the current row in the detail band. The screenshot illustrates that a single value is returned with a simple line of code.

Let's take a look at another more complicated example. Look at step 14 of the Bar Chart example from last chapter. There, we have an expression that looks like:

(row["ORDERDATE"].getYear() + 1900).toString() + '-' + (row["ORDERDATE"].getMonth() + 1).toString()

This Expression retrieves the ORDERDATE value from the current row using the row array, and in two separate parts—one part will retrieve the year and another will retrieve the month using the standard Javascript functions getYear and getMonth. In BIRT, getYear will return the number of years since the epoch, which is 1900. So, in order to get the actual number of years, we need to add 1900 to the result. Therefore, for the year 2007, the result from getYear will return 107, so adding 1900 will return 2007. The situation arises with getMonth; it will return the month from a zero offset. So, January will return 0, February will return 1, and so on, requiring us to add 1 to get the correct month.

As we want to return a string, and the results returned by getYear() and getMonth() are integer or number values, we use the Javascript toString() method to convert these numbers to strings. Finally, we need to concatenate the converted strings and the separating character to get the final result. This Expression, although doing many different things such as retrieving portions of a date value, adding offsets, converting numbers to strings, and then concatenating strings together, returns only a single result.

So, let's get our hands on this. In the following example, we are going to add a line number to the order detail table.

There is now a column with the current line number for the report. While not exactly the most attractive addition, the expression works. We have seen expressions such as these throughout the book. In the Customer Orders report, the Report Title is pulled from the rprmReportTitle parameter using the params["rprmReportTitle"] expression. We use the same row number expression in the highlight example in the Customer Orders report as well.

As we saw with the Bar Chart example, expressions are simply JavaScript. Expressions also have access to JavaScript methods, operators, and objects. In the line number example we just saw, we used the addition operator, and in the Bar Chart example, we used the toString(), getMonth(), and getYear() methods. All assignment, math, comparison, and logical operators available in JavaScript are included. Let's look at the following example that shows the JavaScript string methods being used to return the length of a string:

A simple report with the number 14 should be displayed. The above expression can also be replaced with the following expression.

var testString = "This is a test";
testString.length;

In the example, we are breaking from the one line expression and using multiple lines and a variable. The key is that the last line is returning a single value. All sorts of computations can take place, as long a single value is returned. Now consider we change the expression to the following:

var testString = "This is a test";
var splitString = testString.split(" ");
splitString[3].toUpperCase();

The report will now return only the word TEST. Again, while multiple things are being done in this expression such as the assignment of the string, splitting the string, and converting the element 3 to upper case, only a single result is returned.

At the end of Chapter 6, Report Parameters, we went through an exercise where we set a default parameter, using expressions in BIRT's new expression-based default parameter value mechanism, to set a range of current date minus 20 days as a start date and current date as the end date. This exercise is an example of using more complex expressions.

//bring in the java.util package into the scripting scope
importPackage( java.util );
//create a new GregorianCalendar object
var cal = new java.util.GregorianCalendar();
//set the date to now
cal.setTime(new Date());
//substract 20 days
cal.add(Calendar.DAY_OF_MONTH, -20);
//return the start date
cal.getTime();

In this example, we utilized some Java objects that were in the execution environment's classpath. Any Java object in a classpath can be utilized in BIRT expressions, as long as the importPackage method is called or it is referenced with the Packages.path syntax. For example, we used importPackage( java.util ) to import the java.util package. But we could have omitted that line and just as easily declared the GregorianCalendar as:

var cal = new java.util.GregorianCalendar();

The reason for this is that as the Eclipse environment already has the java.util package loaded, so there is no need to explicitly load it with the importPackage call. The key to complex expressions are that a single value gets returned, as in the result of the last line of our expression, cal.getTime(), which returned a single Date value.

Now if Expressions are simple lines of code that return a single value, how do Event Handlers fit into the scripting world of BIRT? The answer is simple—they do exactly what they claim they do, handle events. What does that mean exactly?

Well, to understand that we need to look at how BIRT reports are generated. BIRT Reports are generated in phases. As explained in the BIRT Report Object Model Scripting Specification at http://www.eclipse.org/birt/phoenix/ref/ROM_Scripting_SPEC.pdf, there are five phases in the report generation lifecycle.

In each one of these phases, particular events are triggered that allow the report developer to override the default behavior of the report generation. This allows us to do all sorts of advanced things with BIRT such as custom filtering of data, dynamically adding or removing BIRT objects to the report, or even building an entire BIRT report through script.

Let's simplify things just slightly. If we look at the dataset element, we can see five different events are associated with it:

Consider we have two things we need to do with the dataset. First, we need to initialize a counter variable to 0 for the number of rows that are going to be processed. Next, we need to add to the counter each time a row is retrieved. So, these things are important. The order in which these events take place is beforeOpen, afterOpen, onFetch, beforeClose, and afterClose. Therefore, in either beforeOpen or afterOpen, we need to set our variable to 0. Then, in the onFetch event, we need to add 1 to our counter. Let's look at an example of how to do that:

Understanding the order of execution is important. The report's initialize method will get executed before any of the other methods and declare globalCount. Next, the dataset gets generated in the data transform phase calling BeforeOpen and initializing globalCount to 0. During each row request, the globalCount gets incremented by one. And finally, the value of globalCount gets inserted into the data element we dropped into the report design in the factory phase.

From any of the report generation phases, we have access to various contexts. For the most part, each of the five phases has its own context. In addition, there are also a few extra contexts—one for the data row and the other for displaying an element.

In BIRT, contexts are used to access objects within the scripting environment. At a high level, one has access to the Report context. The Report Context is a mapping in the BIRT scripting environment to the Java object IReportContext, inside the org.eclipse.birt.report.engine.api.script package. This object allows script developers access to the design object, report parameters, and various other aspects of the report. Many of these objects are shorthanded by other, easier-to-use references such as using the params array to access report parameters. Let's take a look at how to access the report context.

In the last modification, we didn't use a local context. Instead, we used the global reportContext to access the reports parameters and used the report context's getParameterValue()method to retrieve the value entered in accessMe.

valueFromScript = reportContext.getParameterValue("accessMe") + " modified";
//import the needed packages from the Java API
importPackage(Packages.org.eclipse.birt.report.model.api);
importPackage(Packages.org.eclipse.birt.report.model.api.elements);
//using the report context, get the design handle
design = reportContext.getReportRunnable().designHandle;
//get the element factory to create the new label
elementFactory = design.getElementFactory();
dataElement = elementFactory.newLabel("testElement");
//set the text from the valueFromScript variable and add
//to the report designs body
dataElement.setText(valueFromScript);
design.getDesignHandle().getBody().add(dataElement);

reportContext.getReportRunnable().designHandle.getDesignHandle().findElement("dataElementToRemove").drop();

Adding sorting conditions

In addition to adding report elements, it is also possible to add conditions such as Highlights, Maps, and Sorting conditions. The following example will show how to dynamically add sorting conditions to a report, based on the value of a report parameter checkbox:

1. Create a new report in a BIRT reporting project. Call this new report as customerPaymentDynamicSort.rptdesign.
2. Bring in the dsClassicCars data source from the library.
3. Create a new dataset using the following query:

   select
   *
   from
   CUSTOMERS,
   PAYMENTS
   where
   CUSTOMERS.CUSTOMERNUMBER = PAYMENTS.CUSTOMERNUMBER
   and customers.customernumber = ?
   

4. Name the parameter for the dataset as dsprmCustomerID.
5. Under the dialog window for the dataset parameter, create and link to a report parameter called rptprmCustomerID. Set it as a textbox entry.
   
6. Drag-and-drop the newly created dataset over to the report design pane. Delete all columns except for the following:
   • Customer Number
   • Customer Name
   • Payment Date
   • Amount
   
7. Create a new report parameter called rptprmSortOrder. Set Hidden option checked.
   
8. Add the following script to the OnPrepare event of the table. There are two versions of this script.

   One for BIRT 2.3 and above:

   importPackage(Packages.org.eclipse.birt.report.model.api.simpleapi);
   if ( params["rptprmSortOrder"].value != null )
   if ( params["rptprmSortOrder"].value.length > 0 )
   {
   var sortCondition = SimpleElementFactory.getInstance().createSortCondition();
   switch (params["rptprmSortOrder"].value)
   {
   case "date" :
   sortCondition.setKey("row["PAYMENTDATE"]");
   break;
   case "price" :
   sortCondition.setKey("row["AMOUNT"]");
   break;
   }
   sortCondition.setDirection("asc");
   this.addSortCondition(sortCondition);
   }
   

   The other for BIRT versions prior to 2.3:

   //We only want to add this into our code when the value is not null for the
   //parameter sort
   if ( params["rptprmSortOrder"].value != null )
   {
   //Bring in the BIRT Report Model API and for CONSTANTS
   importPackage( Packages.org.eclipse.birt.report.engine.api.script.element );
   //Create a dynamic sort condition
   var sortCondition = StructureScriptAPIFactory.createSortCondition();
   //Based on the value of the sort parameter, set the appropriate key value for sorting
   switch (params["rptprmSortOrder"].value)
   {
   //Remember that for the key, we need to use the fully qualified row and field name as a string, not as a value
   case "date" :
   sortCondition.setKey("row["PAYMENTDATE"]");
   break;
   case "price" :
   sortCondition.setKey("row["AMOUNT"]");
   break;
   }
   //set condition to ascending order
   sortCondition.setDirection("asc");
   //Add to the table
   this.addSortCondition(sortCondition);
   }
   

   • There are two versions because the scripting packages changed in BIRT 2.3. I am keeping the previous version here as a reference because there are software packages that embedded the older versions of BIRT.
9. In the header row, we need to create hyperlinks that will call this report and pass in parameters to tell which column to sort by. So, save the report as it is, otherwise the parameters will not show up in the drill down dialog. Select the PaymentDate column header.
   
10. In the Property Editor window, from the left-hand side menu, select Hyperlink.
    
11. Click the Edit button.
12. Select hyperlink type as Drill-through.
13. Link to the customerPayment.rptdesign file.
14. Select the rptprmCustomerID field and set the value to params["rptprmCustomerID"].
15. Select the rptprmSortOrder parameter from the Report Parameters list and set the value to "date" with the quotation marks.
16. Set Show target report in to the Same frame option to open report in the same window.
    
17. Do the same thing for the Amount column, except set the value of rptprmSortorder to "price".

With this done, we can now reorder the report in view time when the user clicks on the date or the amount columns. With a little more logic developed in, we can have the report do both ascending and descending sorts, and even have it refresh the report without having to refresh the viewing page.

Sometimes it is preferable to have a single report behave in a particular way based on some environmental factor. Parameters such as Environment Variables, Output Format, and the time of day may affect the way we want a report rendered. In the following example, we are going to use a real life scenario that I encountered when a client wanted a single report to not enable hyperlinks when they rendered to PDF.

If we go to the Run menu, and choose View as HTML, we will see that the report has a hyperlink which, when clicked, opens the BIRT homepage. If we view as a PDF, that hyperlink will not exist and it will just be a label.

In the example that we just saw, we are affecting only the onRender event for output format. This is affecting report generation at the presentation phase. The example uses the report context to determine the output format. If the output format is nothing, the above script will take the labels action property, which is of type org.eclipse.birt.report.engine.api.iaction, and set it to nothing or null. This will essentially cancel any actions for this component when the output format is equal to PDF.

One of the other things we can do with BIRT scripting is create a data source. In the following example, we will create a simple report that will return the numbers 1 through 10 using a scripted data source:

In the example that we just saw, we did a few things in a different but interesting way. First, we created the Scripted Data source. The way this works is that the fetch method needs to return true when data is returned and false when data is not returned. To get data into the returned row into the cnt column, we then use the reportContexts global variable to keep track of the running count.

The last thing we are going to look at in this chapter is using Java objects as Event Handlers instead of JavaScript in the script editor. In order to implement Java-based Event handlers, the designer needs to extend the appropriate Event Handler object. For example, if we are going to implement the last example as a Java object, we would need to extend the org.eclipse.birt.report.engine.api.script.eventadapter.ScriptedDataSetEventAdapter class.

Therefore, to do this, let's create a separate Java project in Eclipse. Let's create a class like the following:

package com.birtbook.eventHandler;
Java objectsJava objectsusing, as event handlersimport org.eclipse.birt.report.engine.api.script.IUpdatableDataSetRow;
import org.eclipse.birt.report.engine.api.script.ScriptException;
import org.eclipse.birt.report.engine.api.script.eventadapter.ScriptedDataSetEventAdapter;
import org.eclipse.birt.report.engine.api.script.instance.IDataSetInstance;
public class ScriptedDataSetHandler extends ScriptedDataSetEventAdapter {
private int currentCount;
@Override
public boolean fetch(IDataSetInstance dataSet, IUpdatableDataSetRow row) {
//increment the counter
currentCount++;
if (currentCount < 11)
{
//set the rows value
try {
row.setColumnValue("cnt", currentCount);
} catch (ScriptException e) {
e.printStackTrace();
}
return true;
}
return false;
}
@Override
public void open(IDataSetInstance dataSet) {
super.open(dataSet);
//initialize the count
currentCount = 0;
}
}

Now, we need to restart Eclipse in order for it to recognize the class in our report design. Then, once we restart Eclipse, we are able to use our class and debug in Eclipse when we run the report. Next, we go into the report design, select my dsCount as the data source, clear all of the script out of the events. Then, under the Event Handler tab in the Property Editor, we click on the Browse… button and select my class. When we run the report, it will use our new class as the event handler.

The benefit to this approach is that it is much easier to debug during development. Plus, we have full access to the Eclipse IDE, code completion, and a much cleaner IDE to develop event handlers with. The drawback is that we would need to deploy the classes with the reports and make sure they are visible in the classpath for our runtime environment.

While Event Handling can be a tricky concept in BIRT, there is something that complicates things even further—charts. Charts use a completely different Event handling mechanism as they are extended item types in BIRT. What this means is that charts are not intrinsic BIRT components. When BIRT executes a Chart, there is a marker saying "Hey, I'm an external component, I need to use the Chart Engine API to execute and Render". Because Charts do not get created until Render time, charts have only an onRender event, with several subevents that internal to the Chart Engine API. This is a little confusing at first. So, let's go through an exercise to illustrate what this means. The following will use BIRT's Chart Event Handler to override the action for a Pie Slice. Pie slices will jump to a corresponding table bookmark for all values except the number 5.

As we can see, chart event handling is much more complex than regular event handling. In the example that we just saw, we had to use Java's reflection mechanism to get access to some properties that are not normally exposed to the end developer in order to change the action of an individual slice. We can also note that there is a submethod called beforeDrawDataPoint that we are implementing. This is an internal Chart Engine API event.

In the following exercise, we are going to look at building a very complex chart interactivity example using a combination of chart interactivities, which get rendered as client side JavaScript, text elements containing client side JavaScript, and BIRT Event Handlers to replicate a chart several times for an old fashioned image swap. It will be important that we use either PNG or JPEG charts as SVG already has its own mechanisms for doing this.