Advanced BIRT Report Customization:: Report and Chart Scripting

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
What is Scripting?
• Custom code to control various aspects of report
creation
• Used as custom event handlers
• Java or JavaScript
Why use scripting?
• Maximum Flexibility
• Data is rarely is the perfect format
• Business rules are rarely an exact science
• Use for Exception handling
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.
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
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
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
BIRT Processing Phases
• BIRT report processing happens in three phases
 Preparation Phase
 Generation Phase
 Presentation Phase
Preparation Phase
• Report items are prepared for execution
Preparation Generation Presentation

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

Phase Phase Phase
RunTask X X
RenderTask
RunAndRenderTask X X
Presentation Phase
• Selects the proper emitter
• Produces the desired output

Phase Phase Phase
RunTask X X
RenderTask X
RunAndRenderTask X X X
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.
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
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
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.
Data Source Events
• beforeOpen()
• open() – only for Scripted Data Sources
• afterOpen()
• beforeClose()
• close() - only for Scripted Data Sources
• afterClose()
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()
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
Event Order Sequence
Phase Phase Phase
RunTask X X
RenderTask X
RunAndRenderTask X X X
Preparation Phase
• Parameter validation
• Initialization
• Report element preparation
Preparation Phase
RunTask RunAndRenderTask
Parameter
Parameter Parameter
Parameter
Parameter
validate() Parameter
validate()
validate()
validate() validate()
validate()
ReportDesign ReportDesign
initialize() initialize()
ReportItem
ReportItem ReportItem
ReportItem
ReportItem
onPrepare() ReportItem
onPrepare()
onPrepare()
onPrepare() onPrepare()
onPrepare()
ReportDesign ReportDesign
beforeFactory() beforeFactory()
ReportDesign
beforeRender()
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
Generation Phase
RunTask RunAndRenderTask
MasterPage Data MasterPage Data
Events Events
MasterPage MasterPage MasterPage

onCreate() onCreate() onRender()
MasterPage MasterPage
onPageBreak() onPageBreak()
Report
ReportBody
BodyData
Data Report
ReportBody
BodyData
Data
Report Body
Events Data Report Body
Events Data
Events
Events Events
Events
Report
ReportItem
Item Report
ReportItem
Item Report
ReportItem
Item
Report
onCreate() Item Report
onCreate() Item Report
onRender()Item
onCreate()
onCreate() onCreate()
onCreate() onCreate()
onCreate()
Report
ReportBody
Body Report
ReportBody
Body
Report Body
onPageBreak() Report Body
onPageBreak()
onPageBreak()
onPageBreak() onPageBreak()
onPageBreak()
Report Element Processing
• Processing is Iterative
• Nested Elements are processed
before moving to the next element
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
Table or List Event Processing
• Event order is altered for each row of data returned
• Data rows are processed with row containers
Row Event Order Processing
RunTask
Row.onCreate
RunAndRenderTask
Repeat for every cell in a row Row.onCreate
Cell.onCreate Row.onRender
Repeat for every item in a cell Repeat for every cell in a row
Item.onCreate Cell.onCreate
Cell.onRender
Repeat for every item in a cell

RenderTask
Row.onRender Item.onCreate
Item.onRender
Repeat for every cell in a row
Cell.onRender
Repeat for every item in a cell

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

Process Header Row(s)
Process
ProcessDetail
DetailRow
Row
Process Groups and Detail Rows
Process Group Footer Row(s)

Process Footer Row(s)
Completion of Generation Phase
• Data Sources beforeClose() and afterClose() events
are triggered
• afterFactory() event is triggered (RunTask Only)
• afterRender() event is triggered (RunAndRenderTask
only)
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
Report Scripting Examples
Demo
Chart Scripting
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
Java Chart Event Handler
Engine Flow vs Report Engine Phases
Report Engine Chart Engine
Generation Phase 1. prepare
2. bind data
Rendering
Phase
onRender 3. build
4. render
Device
Renderer
Generator.bindData
Chart Model In
beforeDatasetFilled for each afterDatasetFilled for each

Runtime series Runtime series
Optional
Grouping
Design Series Runtime Series NumberDataSet
Data Runtime Series NumberDataSet
Chart Model With Bound DataSet Out
Events
Generator.build
Chart Model Bound to DataSet
beforeGeneration
Title Block Legend Rendering Hints
Legend
Runtime Series Plot Block Series Rendering Hints
Block
Data Point Hints

afterGeneration Main Block
Series Renders Chart Model

Internally Computed Chart GenerateChartState Out Runtime Context
DisplayServer
Optional Axis With

Events
Min Max and Scale
Set Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0
Generator.render
GenerateChartState In
For Each Series Renderer
Display Server
*Render Main Block
*Render Title Block
Render Plot Block Device Renderer
*Render Background
Draw Primitives – DrawOval, DrawPolygon,
*Render Axis Structure drawText, FillArea, etc
Render Series
Series Specific (ie Bar)
**Render Axis Labels
**Render Legend Block
•*Only the first Series Renderer iterate

•**Only the last Series Renderer
Events See next 2 slides
Render Events
beforeRendering
Series Render Event order vary
beforeDrawBlock - Main depending on Renderer – Bar chart
shown
afterDrawBlock - Main
beforeDrawBlock – Plot – for each series
beforeDrawBlock - Title
beforeDrawSeries
afterDrawBlock - Title
beforeDrawDataPoint
beforeDrawBlock - Plot
afterDrawDataPoint
beforeDrawMarkerRange
beforeDrawDataPointLabel
afterDrawMarkerRange
afterDrawDataPointLabel
beforeDrawMarkerLine
beforeDrawFittingCurve
afterDrawMarkerLine
afterDrawFittingCurve
beforeDrawSeries -base
afterDrawSeries
afterDrawSeries - base
afterDrawBlock – Do not call after last series
afterDrawBlock - Plot
RenderSeries
Next Slide iterate
Events
Render Events
Previous Slide
For Each Axis Chart With

Axis
beforeDrawAxisLabel
afterDrawAxisLabel
beforeDrawAxisTitle
afterDrawAxisTitle
afterDrawBlock - Plot
beforeDrawBlock - Legend
beforeDrawLegendItem
afterDrawLegendItem
afterDrawBlock - Legend
afterRendering
iterate
Events
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");
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
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( ) )
{
}
else if ( block.isTitle( ) )
{
block.setBackground( ColorDefinitionImpl.CREAM( ) );
}
}
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
label.getCaption().getColor( ).set( 208, 32, 0);
LOGARITHMIC_LITERAL
}
} TEXT_LITERAL
function beforeDrawAxisTitle(axis, title, scriptContext) DATE_TIME_LITERAL
{
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()
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);
Setup Java Project for Java Event Handlers
ChartEventHandlerAdapter
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");
Chart Scripting Examples
• JavaScript Event Handlers
• Java Event Handler
• Simple Chart API
Chart Client Side Script - Interactivity
Demo
Chart Interactivity – Features Report/Web page
Click
Click/ Hover
Ctrl or Alt Click
Any Event Any Action

(Script, Callback,…)
Chart Interactivity Examples
• Drillthrough
• Mouseover
• SVG
Q&A
Virgil Dodson
Jason Weathersby

Advanced BIRT Report Customization:: Report and Chart Scripting

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Advanced BIRT Report Customization:: Report and Chart Scripting

Uploaded by

Copyright:

Available Formats

Advanced BIRT Report Customization:

Report and Chart Scripting

Virgil Dodson – Actuate Corporation

• Engine Tasks used with the BIRT Designer

 Preview tab, plus rest of Preview icons use RunAndRenderTask

Preparation Generation Presentation

Preparation Generation Presentation

Preparation Generation Presentation

• MasterPage content first…

MasterPage MasterPage MasterPage

Repeat for every item in a cell

Repeat for every item in a cell

For every row in the group

Process Group Footer Row(s)

Generation Phase 1. prepare

beforeDatasetFilled for each afterDatasetFilled for each

Design Series Runtime Series NumberDataSet

Data Runtime Series NumberDataSet

Chart Model With Bound DataSet Out

Data Point Hints

Series Renders Chart Model

Optional Axis With

•*Only the first Series Renderer iterate

Next Slide iterate

For Each Axis Chart With

yAxis = chart.getOrthogonalAxes( xAxis, true)[0]

Ctrl or Alt Click

Any Event Any Action

You might also like