The following examples illustrate some of the common functions that you can use JavaScript event handlers to perform.

The onPrepare event fires for all report elements during the preparation phase of the generation process. This location is ideal for changing the design of a particular report element before generating the individual report item instances.

For example, BIRT supports grouping in tables and lists. To permit the user to group the data, you can implement this feature by performing the following developer tasks:

Listing 37‑21 groups a table by country or city using a Boolean parameter to determine the grouping column to use.

The onCreate event fires when the generation process creates an instance of the report element. Writing an event handler for an onCreate event is useful when changing an instance of a report item. The following examples illustrate this concept.

Image elements can source image data from a URL, an embedded image in a report, an image file in the resource folder, or a blob type from a database. To retrieve the data for the image at run time, use an onCreate event handler. Listing 37‑22 illustrates how to use Java to read the data from an image stored on the local file system.

If the image element is in a table, you can choose the selected file based on the data retrieved from the dataset. For example, the onCreate script in Listing 37‑23 selects an image from the resource folder based on calculations made on the table bound columns.

BIRT supports conditional element formatting, using the highlight editor. You can also use the onCreate event handler to do conditional formatting, as shown in Listing 37‑24. This example is an onCreate event handler for a table row. If the table column QUANTITYORDERED is greater than 40, the row height increases to 2 centimeters, is highlighted in yellow, and the content appears in the middle of the row.

Rendering content may occur anytime after generation. Often users run a report and re-render it many times in different formats. The onRender events support some customization at render time. For example, a user may want a label in the page footer to show the render time of the report or the day of the month the report rendered. You can achieve this effect by using the onRender method of a label element, as shown in the following script:

Cross tabs support writing event scripts. As with other report items the cross tab supports an onPrepare, onCreate, and onRender event. Each of these events supports writing a handler for the cross tab or the cross tab cell. When implementing an onCreate event for the cross tab cell, the handler is passed a cellInst object. This object is an instance of a cell object that provides methods to determine the cell properties. For example, the developer can call cellInst.getCellType( ). This method returns either aggregation or header, representing a cross tab. Use the cellInst.getCellID( ) to determine what specific design‑time cell is being processed. This method returns the Element ID defined in the general properties for a cell. The cellInst object also provides a method, getDataValue, which returns the specific value of a cross tab binding at the time the cell is created. The method getStyle( ) supports customizing the appearance of a specific cell.

The script in Listing 37‑25 illustrates the mechanics of using these methods. The script resides in the CrossTab.onCreate method. It is automatically executed for each cell in the CrossTab. The script styles the header cells for rows and columns, checking to see if the dimension value for the specific cell is equal to Planes. If it is, then the background is set to red and the font size is set to 12. All other header cells are set to yellow.

Finally, the cell id is checked and if the element ID is 24, the cell background color is set to orange.

The script in Listing 37‑26 continues the onCreateCell script in Listing 37‑25, handling setting colors for the aggregation elements which make up the bulk of the cross tab. First, if the product line is Planes the cell background color is set to blue-gray. This setting ensures all the cells in the particular row or column that correspond to the Planes value of the product line appear blue‑gray. Finally, if the measure amount is greater than 50000, the cell background color is set to green and the font color is set to white. In this example, you can use getDataValue to retrieve data binding values that are defined in the bindings tab for the cross tab.

Alternatively, you can use the reportContext.evaluate( ) method to evaluate a specific expression. In the example:

and

are equivalent if the expression for the amount_DateGroup/quarter_ProductGroup/PRODUCTLINE binding is measure['amount']. The value for this binding is the value for row‑column intersection point.

Development of a complex report design can make use of libraries to ensure consistent appearance of all items. When a library is used, a change to the parent item in the library changes all report items that descend from that item. However, sometimes a change is required to a complex report design that has been developed without using a library. For example, applying mapping to a library data item can change the appearance of zeros or null values in descendant data items in a report, but if there are a large number of data items that are not controlled by a library item, making changes is tedious and error-prone. In this case, the report developer can use dynamic script generation in the beforeFactory to apply an onRender script to the data items, as shown in Listing 37‑27.