Calling Client Side JavaScript from a BIRT Chart

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.