Advanced BIRT Report Customization: Report and Chart Scripting

1. Advanced BIRT Report Customization: Report and Chart Scripting Virgil Dodson – Actuate Corporation Jason Weathersby – Actuate Corporation

2. Agenda • Report Scripting • Chart Scripting

3. Report Scripting

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

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

6. 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.

7. 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

8. 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

9. 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

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

11. Preparation Phase • Report items are prepared for execution

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

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

14. 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.

15. 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

16. 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

17. 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.

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

19. 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()

20. 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

21. Event Order Sequence

22. Preparation Phase • Parameter validation • Initialization • Report element preparation

23. Preparation Phase RunTask RunAndRenderTask Parameter validate() Parameter validate() Parameter validate() Parameter validate() Parameter validate() Parameter validate() ReportDesign initialize() ReportDesign initialize() ReportItem onPrepare() ReportItem onPrepare() ReportItem onPrepare() ReportItem onPrepare() ReportItem onPrepare() ReportItem onPrepare() ReportDesign beforeFactory() ReportDesign beforeFactory() ReportDesign beforeRender()

24. 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

25. Generation Phase RunTask RunAndRenderTask MasterPage Data Events MasterPage Data Events MasterPage onCreate() MasterPage onCreate() MasterPage onRender() MasterPage onPageBreak() MasterPage onPageBreak() Report Body Data Events Report Body Data Events Report Body Data Events Report Body Data Events Report Body Data Events Report Body Data Events Report Item onCreate() Report Item onCreate() Report Item onRender() Report Item onCreate() Report Item onCreate() Report Item onCreate() Report Item onCreate() Report Item onCreate() Report Item onCreate() Report Body onPageBreak() Report Body onPageBreak() Report Body onPageBreak() Report Body onPageBreak() Report Body onPageBreak() Report Body onPageBreak()

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

27. 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

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

29. 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 RenderTask Repeat for every item in a cell Item.onCreate Row.onRender Item.onRender Repeat for every cell in a row Cell.onRender Repeat for every item in a cell Item.onRender

30. 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 Process 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)

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

32. 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

33. Report Scripting Examples Demo

34. Chart Scripting

35. JavaScript Chart Event Handler

36. Java Chart Event Handler

37. Engine Flow vs Report Engine Phases Chart Engine Report Engine Generation Phase 1. prepare Rendering Phase onRender 2. bind data 3. build 4. render Device Renderer 38

38. Generator.bindData Chart Model In beforeDatasetFilled for each Runtime series afterDatasetFilled for each Runtime series Optional Grouping Design Series Runtime Series NumberDataSet Data Runtime Series NumberDataSet Chart Model With Bound DataSet Out Events

39. Generator.build Chart Model Bound to DataSet beforeGeneration Legend Rendering Hints TitleBlock Series Rendering Hints Runtime Series Legend Block PlotBlock Data Point Hints afterGeneration Main Block GenerateChartState Out Series Renders Chart Model Internally Computed Chart Runtime Context DisplayServer Events Optional Axis With Min Max and Scale Set

40. Generator.render GenerateChartState In For Each Series Renderer Display Server *Render Main Block *Render Title Block Device Renderer Render Plot Block *Render Background Draw Primitives – DrawOval, DrawPolygon, drawText, FillArea, etc *Render Axis Structure Render Series 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

41. beforeRendering Series Render Event order vary depending on Renderer – Bar chart shown Render Events beforeDrawBlock - Main 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

42. 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

43. 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");

44. 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

45. 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); } }

46. 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 { 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() Supported Types LINEAR_LITERAL LOGARITHMIC_LITERAL TEXT_LITERAL DATE_TIME_LITERAL

47. 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); }

48. Setup Java Project for Java Event Handlers

49. ChartEventHandlerAdapter

50. 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");