Advanced BIRT Report Customization

:
Report and Chart Scripting

Virgil Dodson – Actuate Corporation Jason Weathersby – Actuate Corporation

© 2008 by Virgil Dodson; made available under the EPL v1.0 | 2/11/2008

Agenda
• Report Scripting • Chart Scripting

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Report Scripting

© 2008 by Virgil Dodson; made available under the EPL v1.0 | 2/11/2008

What is Scripting?
• Custom code to control various aspects of report creation • Used as custom event handlers • Java or JavaScript

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Why use scripting?
• Maximum Flexibility • Data is rarely is the perfect format • Business rules are rarely an exact science • Use for Exception handling

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Choosing between Java and JavaScript
• Advantages of Scripting with JavaScript
     Easier for single event Simpler language construct Looser typing Less strict language rules Available to RCP applications

• Advantages of Scripting with Java
 Can use Java editor  Easier to find and view scripts  Access to the integrated debugger

Mix and Match! – You can use both Java and JavaScript Events… The

JavaScript event overrides the Java event if the same event exist twice.

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Events Overview
• Events are triggered throughout report execution • Understanding the Event Order is important and depends on:
 Engine Task Processes  BIRT Processing Phases  Event Types

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Engine Task Processes
• Report Engine can be used in different ways
 3 tasks related to report execution and rendering
 RunTask  RenderTask  RunAndRenderTask

 Using RunTask and then RenderTask means multiple processes to generate and view a report.  RunAndRenderTask happens in single process so event firing order is different

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Engine Task Processes (cont.)
• Engine Tasks used with the Example Web Viewer
 ‘frameset’ mapping uses RunTask and RenderTask… export from Viewer uses RenderTask  ‘run’, ‘preview’ mapping uses RunAndRender Task

• Engine Tasks used with the BIRT Designer
 Web Viewer Preview uses RunTask and then RenderTask

 Preview tab, plus rest of Preview icons use RunAndRenderTask

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

BIRT Processing Phases
• BIRT report processing happens in three phases
 Preparation Phase  Generation Phase  Presentation Phase

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Preparation Phase
• Report items are prepared for execution

Preparation Phase RunTask RenderTask RunAndRenderTask

Generation Phase

Presentation Phase

X X

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Generation Phase
• • • • creates the individual instances of report items connects to data sources executes data sets processes data needed for the report

Preparation Phase RunTask RenderTask RunAndRenderTask

Generation Phase

Presentation Phase

X X

X X

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Presentation Phase
• Selects the proper emitter • Produces the desired output

Preparation Phase RunTask RenderTask RunAndRenderTask

Generation Phase

Presentation Phase

X X

X X X X

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

BIRT Event Types
• Parameter events • ReportDesign events • Data Source/Set events • ReportItem events

• Each event type has one ore more events that will fire during report processing.

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Parameter Events
• validate()
 Used for extra validation or modifying parameter value  First event triggered for reports with parameters
 After user enters parameter value  Before rest of report events run

 Only available in JavaScript  Expects true or false returned
 true – process as normal  false – throw parameter not set exception

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Report Design Events
• Fired for all reports • initialize()
 once for each RunTask, RenderTask, or RunAndRenderTask

• beforeFactory()
 Once; after Preparation Phase and before Generation Phase

• afterFactory()
 Once; after Generation Phase

• beforeRender()
 Once for each render task, before Presentation Phase

• afterRender()
 Once for each render task, after Presentation Phase

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Data Source/Set Events
• All data sources and data sets have a common set of event handlers • A scripted Data Source has two additional event handlers • A scripted Data Set has three additional event handlers • Data source/set events are fired prior to being used on a data bound item. • If the data is not used on a report, these events will not fire • Not advisable to write event handlers that rely on the data set event firing order.

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Data Source Events
• beforeOpen() • open() – only for Scripted Data Sources • afterOpen() • beforeClose() • close() - only for Scripted Data Sources • afterClose()

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Data Set Events
• beforeOpen() • open() – only for Scripted Data Sets • afterOpen() • fetch() – required for Scripted Data Sets • onFetch() – as each row of data is retrieved • beforeClose() • close() - only for Scripted Data Sources • afterClose()

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

ReportItem Events
• Triggered for most report items • onPrepare()
 Fired at beginning of Preparation Phase before data binding.  Can be used to change the design of an item prior to creating instances of each item

• onCreate()
 Fired during Generation Phase as item is being created  Can be used to change individual instance of item

• onRender()
 Fired during Presentation Phase  Useful for operations regarding the output format

• onPageBreak()
 Fires for all report items on a page when the break occurs

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Event Order Sequence
Preparation Phase RunTask RenderTask RunAndRenderTask Generation Phase Presentation Phase

X X

X X X X

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Preparation Phase
• Parameter validation • Initialization • Report element preparation

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Preparation Phase
RunTask
Parameter Parameter Parameter validate() validate() validate() ReportDesign initialize() ReportItem ReportItem ReportItem onPrepare() onPrepare() onPrepare() ReportDesign beforeFactory()

RunAndRenderTask
Parameter Parameter Parameter validate() validate() validate() ReportDesign initialize() ReportItem ReportItem ReportItem onPrepare() onPrepare() onPrepare() ReportDesign beforeFactory() ReportDesign beforeRender()

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Generation Phase
• Connecting to Data Sources • Executing Data Sets and Data Cubes • Data Binding Evaluation • Creation of Report Items • MasterPage content first… • …then Top-to-Bottom, Left-to-Right

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Generation Phase
RunTask
MasterPage Data Events MasterPage onCreate() MasterPage onPageBreak() Report Body Data Report Body Data Report Body Data Events Events Events Report Item Report Item Report Item onCreate() onCreate() onCreate() Report Body Report Body Report Body onPageBreak() onPageBreak() onPageBreak()

RunAndRenderTask
MasterPage Data Events MasterPage onCreate() MasterPage onRender()

MasterPage onPageBreak() Report Body Data Report Body Data Report Body Data Events Events Events Report Item Report Item Report Item onCreate() onCreate() onCreate() Report Item Report Item Report Item onRender() onCreate() onCreate()

Report Body Report Body Report Body onPageBreak() onPageBreak() onPageBreak()

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Report Element Processing
• Processing is Iterative • Nested Elements are processed before moving to the next element

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

onPageBreak Event
• Can be set on most elements • Triggered in Generation Phase for RunAndRenderTask • Triggered in Presentation Phase for RenderTask • Only fired for output that supports pagination • onPageBreak event fires just prior to the onCreate event for the first master page element on the next page

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Table or List Event Processing
• Event order is altered for each row of data returned • Data rows are processed with row containers

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Row Event Order Processing
RunTask
Row.onCreate
Repeat for every cell in a row

RunAndRenderTask
Row.onCreate Row.onRender
Repeat for every cell in a row

Cell.onCreate
Repeat for every item in a cell

Item.onCreate

Cell.onCreate Cell.onRender

RenderTask
Row.onRender
Repeat for every cell in a row

Repeat for every item in a cell

Item.onCreate Item.onRender

Cell.onRender
Repeat for every item in a cell

Item.onRender

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Table or List Order Processing
DataSet.beforeOpen DataSet.afterOpen DataSet.onFetch DataSet.onFetch Table.onCreate Table.onRender Cell.onRender
Process Header Row(s) For every group level in the table Process Group Header Row(s)

For every row in the group

Process Detail Row Process Detail Row
Process Groups and Detail Rows Process Group Footer Row(s) Process Footer Row(s)

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Completion of Generation Phase
• Data Sources beforeClose() and afterClose() events are triggered • afterFactory() event is triggered (RunTask Only) • afterRender() event is triggered (RunAndRenderTask only)

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Presentation Phase
• onRender events triggered for all report items • Initialize() is triggered RenderTask only • When rendering individual pages, only onRender events on that page will be triggered

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Report Scripting Examples

Demo

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Chart Scripting

© 2008 by Virgil Dodson; made available under the EPL v1.0 | 2/11/2008

Chart Model Edit – Scripting
 Goal
 Change Formatting/Font/Colors/Labels/Visibility  Use data point values or external context  Typical use: Conditional Formatting

 Scripting languages
 JavaScript  Java

 JavaScript
 Access Java Chart Model  importPackages(Packages.org.eclipse.birt.XXX)

35

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

JavaScript Chart Event Handler

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Java Chart Event Handler

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Engine Flow vs Report Engine Phases
Report Engine
Generation Phase

Chart Engine 1. prepare

2. bind data
Rendering Phase onRender

3. build

4. render

Device Renderer
38 Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Generator.bindData
Chart Model In

Optional Grouping

beforeDatasetFilled for each Runtime series

afterDatasetFilled for each Runtime series

Design Series Data

Runtime Series Runtime Series

NumberDataSet NumberDataSet

Chart Model With Bound DataSet Out

Events
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Generator.build
Chart Model Bound to DataSet
beforeGeneration Title Block

Legend Rendering Hints
Legend Block

Runtime Series

Plot Block

Series Rendering Hints

Data Point Hints
afterGeneration Main Block

Series Renders Internally Computed Chart DisplayServer

Chart Model

GenerateChartState Out

Runtime Context

Optional Axis With Min Max and Scale Set Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Events

Generator.render
GenerateChartState In
For Each Series Renderer *Render Main Block *Render Title Block Render Plot Block *Render Background *Render Axis Structure Render Series **Render Axis Labels **Render Legend Block
Draw Primitives – DrawOval, DrawPolygon, drawText, FillArea, etc

Display Server

Device Renderer

Series Specific (ie Bar)

•*Only the first Series Renderer •**Only the last Series Renderer

iterate

Events See next 2 slides

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Render Events
beforeRendering beforeDrawBlock - Main afterDrawBlock - Main beforeDrawBlock - Title afterDrawBlock - Title beforeDrawBlock - Plot beforeDrawMarkerRange afterDrawMarkerRange beforeDrawMarkerLine afterDrawMarkerLine beforeDrawSeries -base afterDrawSeries - base afterDrawBlock - Plot RenderSeries Next Slide iterate Series Render Event order vary depending on Renderer – Bar chart shown beforeDrawBlock – Plot – for each series beforeDrawSeries beforeDrawDataPoint afterDrawDataPoint beforeDrawDataPointLabel afterDrawDataPointLabel beforeDrawFittingCurve afterDrawFittingCurve afterDrawSeries afterDrawBlock – Do not call after last series

Events
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Render Events
Previous Slide For Each Axis beforeDrawAxisLabel afterDrawAxisLabel beforeDrawAxisTitle afterDrawAxisTitle afterDrawBlock - Plot beforeDrawBlock - Legend beforeDrawLegendItem afterDrawLegendItem afterDrawBlock - Legend afterRendering iterate Chart With Axis

Events
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Getting the Report Context from the Chart Context
• In JavaScript
 rpcntx = context.getExternalContext().getScriptable();  rpcntx.getParameterValue("chartTitle");

• In Java
 IReportContext rc = (IReportContext)icsc.getExternalContext().getObject();  String mytitle = (String)rc.getParameterValue("chartTitle");

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Iterative script calls
• Many of the script calls are iterative • For example the before and afterDataSetFilled and before and afterDrawSeries. • Use series.getSeriesIdentifier() to key on a particular series. • function beforeDrawSeries( series, seriesRenderer, context )
{ if( series.getSeriesIdentifier() == "series one" ){ context.getChartInstance(). setUnitSpacing(70); } }
//This

will not work with grouped series definitions
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Iterative script calls .. Blocks Similar
public void beforeDrawBlock( Block block, IChartScriptContext icsc ) { if ( block.isCustom( ) ) { //Main Block } if ( block.isLegend( ) ) { block.getOutline( ).setVisible( true ); block.getOutline( ).getColor( ).set( 255, 0, 0); } else if ( block.isPlot( ) ) { block.getOutline( ).setVisible( true ); block.getOutline( ).getColor( ).set( 0, 255, 0); } else if ( block.isTitle( ) ) { block.getOutline( ).setVisible( true ); block.setBackground( ColorDefinitionImpl.CREAM( ) ); block.getOutline( ).getColor( ).set( 0, 0, 255); } }
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Iterative -- Determining Which Axis the event occurs for
function beforeDrawAxisLabel(axis, label, scriptContext)
{

importPackage(Packages.org.eclipse.birt.chart.model.attribute); if (axis.getType() == AxisType.TEXT_LITERAL)
{

label.getCaption( ).getColor( ).set( 140, 198, 62 );
}

else
{

Supported Types
LINEAR_LITERAL LOGARITHMIC_LITERAL TEXT_LITERAL DATE_TIME_LITERAL

label.getCaption().getColor( ).set( 208, 32, 0);
} }

function beforeDrawAxisTitle(axis, title, scriptContext)
{

importPackage(Packages.org.eclipse.birt.chart.model.attribute); if (axis.getType() == AxisType.LINEAR_LITERAL)
{

title.getCaption( ).setValue( "Y-Axis Title By JavaScript");
}

title.getCaption( ).getColor( ).set( 32, 168, 255 );
}

//Can also use: //axis.getTitle().getCaption().getValue()
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Getting Axis
function beforeGeneration(chart, icsc) { importPackage( Packages.org.eclipse.birt.chart.model.attribute.impl ); importPackage( Packages.org.eclipse.birt.chart.model.data.impl ); xAxis = chart.getBaseAxes()[0]; xAxis.setFormatSpecifier( JavaDateFormatSpecifierImpl.create("MM//dd/yyyy")); yAxis = chart.getOrthogonalAxes( xAxis, true)[0] yscale = yAxis.getScale(); yscale.setStep (10); yscale.setMin( NumberDataElementImpl.create(1.5) ) yscale.setMax( NumberDataElementImpl.create(100) ) yAxis.setScale(yscale); }

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Setup Java Project for Java Event Handlers

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

ChartEventHandlerAdapter

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Simple Charting API
• New API that can be used in the Report Script. See Java Docs.
• • • • • • • Example beforeFactory script //Simple Chart Api rptDesignHandle = reportContext.getReportRunnable().designHandle.getDesignHandle(); cht = rptDesignHandle.findElement("Chart1"); cht.setProperty( "style", "NewStyle1" ); var chart1 = this.getReportElement( "Chart1" ); var color1 = chart1.getTitle().getCaption().getColor();

• chart1.setColorByCategory( true ); • chart1.getTitle().getCaption().setValue( "My New Title" ); • • • • • • • • • • • • • • color1.setRed( 255 ); color1.setGreen( 0 ); color1.setBlue( 0 ); chart1.getTitle().getCaption().setColor( color1 ); chart1.setDimension( "ThreeDimensional" ); chart1.getCategory().setSorting( "Descending" ) chart1.setWidth("6in"); chart1.setHeight("6in"); //Standard API More Complex than Simple Chart API importPackage( Packages.org.eclipse.birt.chart.model ); chart = rptDesignHandle.findElement("Chart1" ); item = chart.getReportItem(); cm = item.getProperty("chart.instance"); cm.getTitle().getLabel().getCaption().setValue("My Test");
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Chart Scripting Examples
• JavaScript Event Handlers • Java Event Handler • Simple Chart API

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Chart Client Side Script - Interactivity

Demo

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Chart Interactivity – Features
Click

Report/Web page

Click/ Hover

Ctrl or Alt Click

Any Event

Any Action (Script, Callback,…)

54

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Chart Interactivity Examples
• Drillthrough • Mouseover • SVG

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Q&A
Virgil Dodson Jason Weathersby

Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0

Master your semester with Scribd & The New York Times

Special offer for students: Only $4.99/month.

Master your semester with Scribd & The New York Times

Cancel anytime.