Transcript Document

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
Generation
Phase
Presentation
Phase
X
RenderTask
RunAndRenderTask
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
RunTask
Preparation
Phase
Generation
Phase
X
X
X
X
Presentation
Phase
RenderTask
RunAndRenderTask
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
RunTask
Preparation
Phase
Generation
Phase
X
X
RenderTask
RunAndRenderTask
Presentation
Phase
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 or 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
RunTask
Preparation
Phase
Generation
Phase
X
X
RenderTask
RunAndRenderTask
Presentation
Phase
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
RunAndRenderTask
Parameter
Parameter
Parameter
validate()
validate()
validate()
Parameter
Parameter
Parameter
validate()
validate()
validate()
ReportDesign
initialize()
ReportDesign
initialize()
ReportItem
ReportItem
ReportItem
onPrepare()
onPrepare()
onPrepare()
ReportItem
ReportItem
ReportItem
onPrepare()
onPrepare()
onPrepare()
ReportDesign
beforeFactory()
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
RunAndRenderTask
MasterPage Data
Events
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()
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
Cell.onCreate
Repeat for every item in a cell
Item.onCreate
RunAndRenderTask
Row.onCreate
Row.onRender
Repeat for every cell in a row
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
For every group level in the table
Process Group Header Row(s)
Cell.onRender
Process Header Row(s)
For every row in the group
Process
ProcessDetail
DetailRow
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
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
Chart Engine
Generation Phase
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
Design Series
Data
beforeDatasetFilled for each
Runtime series
afterDatasetFilled for each
Runtime series
Runtime Series
NumberDataSet
Runtime Series
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
Runtime Series
Plot Block
Legend Rendering Hints
Legend
Series Rendering Hints
Block
Data Point Hints
afterGeneration
Main Block
Series Renders
Internally Computed Chart
Chart Model
GenerateChartState Out
Runtime Context
DisplayServer
Events
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
Generator.render
GenerateChartState In
For Each Series Renderer
Display Server
*Render Main Block
*Render Title Block
Device Renderer
Render Plot Block
*Render Background
*Render Axis Structure
Render Series
Draw Primitives – DrawOval, DrawPolygon,
drawText, FillArea, etc
Series Specific (ie Bar)
**Render Axis Labels
**Render Legend Block
•*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
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
RenderSeries
Next Slide
iterate
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
Chart With
Axis
afterDrawAxisLabel
beforeDrawAxisTitle
afterDrawAxisTitle
afterDrawBlock - Plot
beforeDrawBlock - Legend
beforeDrawLegendItem
afterDrawLegendItem
afterDrawBlock - Legend
afterRendering
iterate
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
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()
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
Report/Web page
Click
Hyperlink /Drill-Through
Tooltips
Highlight/Hide
(Swing/SWT/SVG)
Click/ Hover
Ctrl or Alt Click
SVG Zoom/Pan
Any Event
Custom Interactivity
54
Any Action
(Script, Callback,…)
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
BIRT Exchange Community Site
Centralized Knowledge Hub for BIRT Developers
• Access Downloads, Demos, Tutorials, Tips & Techniques, Webinars
• Easy for users to contribute content, share knowledge
• Enables developers to be more productive and build applications faster
www.birt-exchange.com
Download
• Documentation
• Software
Share Knowledge
• Reports, Code, Tips
• Forums
Find
• Search, Sort
• Rate, Comment
Advanced BIRT Report Customization | Report Scripting | © 2008 by Virgil Dodson; made available under the EPL v1.0