Chapter 7. Using Scripting in a Report Design

BIRT provides a powerful scripting capability that enables a report developer to create custom code to control various aspects of report creation. This chapter provides an overview of scripting in BIRT. Subsequent chapters focus on implementing script event handlers in JavaScript and Java, writing event handlers for charts, and accessing data using scripted data sources.

Overview of BIRT scripting

BIRT Report Designer supports writing custom event handlers in both Java and JavaScript. BIRT RCP Report Designer supports writing custom event handlers only in JavaScript.

Choosing between JavaScript and Java

Both JavaScript and Java have advantages and disadvantages when writing an event handler. For a developer who is familiar with only one of the two languages, the advantage of using the familiar language is obvious, but for others the decision depends on the report requirements.

The advantages of using JavaScript to write an event handler include:

• Ease of adding a simple script for a particular event handler

Adding a JavaScript event handler to a report is less complicated than adding an event handler written in Java. To write a JavaScript event handler, there is no need to create a Java environment in Eclipse or to learn the Eclipse Java development process. There is no requirement to specify a package, implement an interface, or know the parameters of the event handler you write.

To add a JavaScript event handler, first select the name of the event handler from a drop-down list on the Script tab. Then, type the code.

• Simpler language constructs, looser typing, and less strict language rules JavaScript is less demanding to code than Java due to its more relaxed requirements.

The advantages of using Java to write an event handler include:

• Availability of the Eclipse Java development environment

The Eclipse Java development environment is very powerful and includes such features as autocompletion, context sensitive help, keyboard shortcuts, and parameter hints.

• Ease of finding and viewing event handlers

All the Java event handlers for a report exist in readily viewable Java files. By contrast, the JavaScript event handlers are embedded in the design and you can view only one handler at a time.

Using both JavaScript and Java

There is no requirement to write all event handlers in one language. You can write some in JavaScript and others in Java. If both a JavaScript and a Java event handler for the same event are available, BIRT uses the JavaScript handler.

Events overview

When writing event handlers, understanding the event order is imperative. The order in which events fire depends on several factors. These factors include which BIRT processing phase is executing, the engine task executing the process, and what event type is processing.

Engine task processes

The scripting chapters make continuous reference to engine task processes. This section provides an overview of what these processes are and how they affect scripting.

The Report Engine that executes reports is task-oriented and provides three tasks related to the execution and rendering of reports. These tasks are RunAndRenderTask, RunTask, and RenderTask.

The RunAndRenderTask uses one process to open the report design and produce a specific output, such as PDF. The RunTask opens a report design and executes the report producing a report document file with a .rptdocument extension. This report document is an intermediate binary file that can then be used by a RenderTask to produce a report output type, such as HTML, PDF, PPT, PS, Word, or XLS. The RenderTask opens a report document (.rptdocument) and renders the appropriate output format. This task can be executed any time after a RunTask. This task can even occur on a separate system.

BIRT Report Designer uses the report engine to show a preview of a report. Selecting Preview in the Editor launches a RunAndRenderTask to produce the report. Selecting any other previewing option in BIRT Report Designer toolbar launches a RunAndRenderTask to produce the output, with the exception of the Run report in BIRT Web Viewer, which produces the report using a RunTask followed by a RenderTask.

The tasks RunTask and RenderTask can be used when the tasks need to occur at separate times or on separate systems. Using separate run and render tasks therefore requires two processes to run and render a report to a particular output format.

When RunAndRenderTask processes a report, the event firing order is different from the RunTask and RenderTask are used as two separate processes. The differences in processing are discussed throughout these chapters.

The following sections describe how the report engine processes reports in the BIRT Report Designer environment.

BIRT Web Viewer

The example BIRT Web Viewer application is a J2EE application that encapsulates the report engine to produce reports. This viewer contains three Servlet mappings used to generate reports. These are the frameset, run, and preview mappings.

In the example web viewer, two processes, RunTask and RenderTask, generate and render to the output format to create a report document. Selecting the Export report icon in the Web Viewer toolbar initiates a RenderTask to execute on the current report document.

BIRT processing phases

The BIRT services for generating and presenting report data create a report during the following processing phases:

• Preparation

RunTask or RunAndRender Task prepare the report items for execution.

• Generation

RunTask or RunAndRender Task create an instance of each report item, connect to the data source, execute the data sets, and process the data to produce the report.

• Presentation

RenderTask or RunAndRender Task select the correct emitters to produce the output specified for the report.

The RunTask handles the preparation and generation phases and the Render Task handles the presentation phase. RunAndRenderTask handles all phases of report processing. The types of events and the order in which these events fire depends on the processing phase currently executing in an engine task.

BIRT event types

BIRT supports the following types of events:

• Parameter

• Report design

• Data source and data set

• Report item

Each event type has a series of events that fire during report processing.

Parameter events

BIRT currently supports two parameter level events that can be used to customize the parameter selection choices and default values before the parameter entry box is displayed. In addition, BIRT supports one parameter level event that is called after the parameters have been selected. These events are summarized in Table 7-1. These events are currently available only in JavaScript. Parameter events fire only if the report contains parameters.

Table 7-1 Parameter events

image

Listing 7-1 provides an example of getDefaultValueList and getSelectionValueList event handlers for a parameter formatted as a list box. The array dSLArray contains four values that a report user can select. The array dVLArray contains two values that are the default values of the parameter. These values are selected in the list of available values when the user runs the report.

Listing 7-1 Example event handlers for a parameter formatted as a list box


//getDefaultValueList
var dVLArray = [];
dVLArray[0]= "10104";
dVLArray[1] = "10108";
dVLArray;

//getSelectionValueList
var dSLArray = [];
dSLArray[0]= "10101";
dSLArray[1]= "10104";
dSLArray[2]= "10105";
dSLArray[3] = "10108";
dSLArray;

The getDefaultValueList can be useful to provide date parameters as well.

If changes to the parameter are necessary after a user enters a parameter or if extra parameter validation is required, write an event handler for the validate event. The following example shows a validate script for a string parameter:

params["MyParameter"].value = "Something Else";
true;

Report design events

Report design events fire for all reports. Table 7-2 describes these events. The events support event handlers to provide additional processing of the report.

Table 7-2 Report design events

image

image

Types of data source and data set events

There are several kinds of data sources and data sets. A data source can be a flat file, a JDBC data source, a scripted data source, a web services data source, or an XML data source. All data sources have a common set of event handlers. A scripted data source has two additional event handlers.

Data set events can be called multiple times to support multipass aggregation and data set sharing. It is not advisable to write event handlers that rely on the data set event firing order. An additional issue is that data set event handlers may only be called once because of data set caching.

Table 7-3 describes the data source events.

Table 7-3 Data source events

image

Data source and data set events fire in the generation phase prior to the onCreate event of the report item that uses them. Data set events can fire several times. The event order is covered in more detail later in this chapter. Table 7-4 describes the data set events.

Table 7-4 Data set events

image

Data source and data set events fire prior to being used on a data bound item. If the data set is never used in the report, the data source and data set are never called. A scripted data set is a data set that accesses a scripted data source. A non-scripted data set is one that accesses a standard data source. Use the scripted data source and data set to write custom code to retrieve data values.

Scripted data source events

A scripted data source contains the afterOpen, afterClose, beforeOpen, and beforeClose events common to all data sources, and open and close events. Use the event handlers for the open and close events to perform the actions of opening and closing the data source.

Scripted data set events

A scripted data set contains the afterOpen, afterClose, OnFetch, beforeOpen, beforeClose, open, close, and fetch events. Use the event handlers for the open and close events to perform the actions of opening and closing the data set. Use the fetch method to fetch a row from the data source. Using a scripted data set requires an event handler to be written for the fetch event.

ReportItem events

ReportItem events trigger for report items that are placed in the report. Most items support writing event handlers for the events listed in Table 7-5.

Table 7-5 Report item events

image

Event order sequence

Table 7-6 summarizes which engine task is responsible for a particular phase. The following sections describe the order of event firing for each phase in more detail.

Table 7-6 Engine task by phase

image

Preparation phase operation

The preparation phase includes parameter validation as well as initialization and report element preparation for every element in the report. The preparation phase is identical for all reports. Table 7-7 lists the event types for RunTask and RunAndRenderTask in the order in which the events execute.

The RenderTask does not have a preparation phase. In a RunAndRenderTask, the preparation phase triggers a beforeRender event.

Table 7-7 Preparation phase events

image

The parameter events fire first for each parameter. Before the parameter entry box is displayed, the getDefaultValueList is called for each parameter. This script returns either a single value or a list of values, depending on the parameter type.

Next, each parameter that provides a list of choices to the user calls the getSelectionValueList. If running reports using the API for RunTask or RunAndRenderTask, the getDefaultValueList script event fires for only parameters that have no value passed. The getSelectionValueList is not called. If using createGetParameterDefinitionTask to build your own parameter entry screen, these events fire much like the example Viewer.

After a user enters values for the parameters, the next event is the validate event, which fires for each parameter. The ReportDesign event, initialize, follows. The initialize event fires once when using only one engine task. Using a separate engine task triggers the initialize event at least two times, one time for the preparation phase, and a second time for the render phase. Additional render tasks or phases also trigger the initialize method.

After the initialize event, the preparation phase triggers the onPrepare event for every element in the report. This process starts with the master page content and proceeds from left to right and top to bottom in the report body. All nested elements process before proceeding to the next element.

The beforeFactory event fires next. This event signals that report creation is about to occur and provides a location for altering a running report.

The beforeRender event fires when using a RunAndRenderTask. When using two tasks, this event does not fire until a render operation occurs.

Generation phase operation

The generation phase includes connecting to data sources, executing data sets and data cubes, evaluating data bindings, and creating all the report items in the report. The data source and data set events fire before the creation of data-bound items, but this processing may not occur before the creation of other report items. For example, if a table is bound to a data set and the report uses a master page with only a label in the footer, the master page content onCreate event fires before the data source and data set events for the data set bound to the table.

This phase triggers the onCreate event for every report item. BIRT processes the report body after processing content on the master page. The report body contains all the report items to be created and rendered. BIRT processes all items at all levels in an iterative fashion, following the same process at each level as it does for the top-level items. A report item that is not contained in another report item is called a top-level report item. BIRT processes the top-level items, going from left to right and proceeding a row at a time toward the bottom right. Every report has at least one top-level report item, usually a grid, list, or table. All nested elements complete OnCreate processing before the next element’s onCreate fires.

For each top-level item, BIRT processes all the second-level items before proceeding to the next top-level item. A second-level report item is a report item that is contained within a top-level item. For example, a table contained in a grid is a second-level report item.

There can be any number of levels of report items. To see the level of a particular report item, examine the structure of the report design in Outline, in the BIRT Report Designer, as shown in Figure 7-1.

Figure 7-1 Outline showing the level of a report item

image

If a RunAndRenderTask process executes the generation phase, each element is created and immediately rendered, which fires the onRender event before proceeding to the next element. If a RunTask process executes the generation phase, the onRender events do not fire.

Table 7-8 lists the events triggered in the generation phase for each major report component in the order in which these events execute. The data source, data set, and onPageBreak events are optional.

Table 7-8 Generation phase events

image

Data source and data set events do not fire if a report item is not data bound or if the report item is bound to another report item that executed previously. The onPageBreak event fires only when an actual page break occurs.

The next three sections describe the data source, data set, data binding, and page break events in more detail.

About data source and data set events

Events for data source and data set elements fire just prior to creating the report item bound to the data set. This sequence occurs for every report item bound to a data set with the exception of the data source beforeOpen and afterOpen events. These events do not fire if a data source has already been used. When a report item is bound to another report item, none of these events fire for the bound report item, supporting two data-bound items sharing one data set without re-executing the data set.

The data source beforeClose and afterClose events fire at the end of the generation phase just before the afterFactory event fires. In the generation phase, there is no difference in data source or data set processing in RunTask and RunAndRenderTask.

BIRT supports data set caching, by which data sets execute only once and are used multiple times. In this case, the data set events fire on only the first use. If a data set is parameterized and the actual parameter value is changed within a report item, the query executes again using the new parameter value. This query execution causes the data set events to fire again. Table 7-9 lists the data source and data set types and events in the order in which these events execute.

Table 7-9 Data source and data set events

image

About data binding

Data binding in BIRT makes a logical separation between BIRT data sets and data-bound elements, such as tables and lists. Selecting a table or list and then the Binding tab in the Property Editor displays the current bindings for the item. A report developer can create bound columns that use external objects to calculate a specific column value. The bound data set continues to determine the number of rows that are processed for a given table or list.

In a table or list, evaluation of the data bindings for the detail rows occurs before the onCreate event on the current row. This approach supports the onCreate event handler retrieving the appropriate values for the row.

The bindings are evaluated for each detail row in a bound data set. Table footers containing data elements that use a binding are evaluated before the last onCreate event for the final detail row.

Trying to alter a bound column using the onCreate script is discouraged. For example, it is possible to concatenate a column value for a row with all previous rows for the given column using the onCreate script with a JavaScript variable. If this value is in the expression of a bound column, the last value is excluded from the bound column. To display the last value, use a computed column, an aggregation report item, or the dynamic text <VALUE-OF> tag in a text element to display the JavaScript value.

A report developer must not assume any particular evaluation order of binding expressions relative to the various table item events, except that a binding evaluates before the onCreate event of an item that uses it. Best practice is to perform any required manipulation of the data in a data set script or the binding expression.

Data binding evaluation for a group evaluates the bound column many times before creating the table or list item. BIRT performs multiple passes over the data to support grouping. Any script in a group-bound column expression is called every time the data binding evaluates, affecting report performance.

All bindings of a table are always calculated, whether or not these bindings are used by the table. For performance reasons, check the binding list and remove any unused items from the report design.

Report items can share data bindings. For example, two tables can share the same set of bindings. The second table does not re-evaluate the data bindings. To use this feature in the BIRT Report Designer, select the second table, choose Binding in Property Editor, select Report Item, and select the appropriate report item from the list. The list supports only named data-bound report items.

The above scenarios affect any BIRT expression that uses the Available Column Bindings category.

About page break events

Many report items support page breaks. Setting a page break interval on a table instructs the table to process a certain number of rows and then apply a page break. Setting a page break on a group section applies a page break both before and after or only after the group processes. A page break can be applied before many other report items. For example, applying a page break before a row in a table instructs the engine to apply a page break before every row of data that a table processes.

Page events are based on the paginated HTML emitter. If a report generates 5 HTML pages but has 20 PDF pages, the page events fire only 5 times.

The general order of the events is as follows.

• The engine creates the page.

• The onPageStart event fires for the report.

• The onPageStart event fires for the selected master page.

• For items that are to appear on the page, the onPageBreak event fires.

• The onPageEnd event fires for the selected master page.

• The onPageEnd event for the report fires.

• The engine evaluates the Master Page Auto Text fields.

The onCreate events for all items that are to appear on a page fire before the report’s onStart event. Some items have their onCreate triggered but do not appear on a page because of the keep together flag. Such items appear on the following page.

The page-level scripts are used when the Run and Render tasks are separated.

About chart event order

Chart events are handled by the chart engine and execute within the presentation phase. These events are covered in a later chapter.

About table and list event order

The BIRT engine fires the onCreate event for report items iteratively. When processing report items that iterate over data rows, such as a table or list, the event order changes to add additional events for each row of data. Row containers process data rows.

Row execution sequence

Tables, lists, and groups have rows. BIRT processes all rows identically. There are three kinds of rows:

• Header

• Detail

• Footer

Figure 7-2 illustrates the execution sequence for a row. A list or table can contain multiple elements, such as detail rows or table header rows.

Figure 7-2 Row execution sequence

image

Table and list method execution sequence

A list is equivalent to a table that has only a single cell in every row. BIRT processes tables and lists identically, except that for a list, BIRT does not iterate through multiple cells. BIRT processes tables in three steps, the setup, detail, and wrap-up processing steps.

The following sections describe the table and list execution sequence steps.

Table and list setup step

The pre-table processing step is the same for all tables, both grouped and ungrouped.

Figure 7-3 illustrates the execution sequence for the pre-table processing step. This illustration shows the event order when using a RunAndRenderTask in the generation phase.

Figure 7-3 Table and list setup execution sequence

image

A RunTask does not fire onRender events. A RenderTask does not fire onCreate, data source, and data set events. The data source and data set events are optional.

Table and list processing step

The sequence for the table and list processing step depends on whether the table or list is grouped. A table or list having no grouping has a different sequence from one that has grouping.

Figure 7-4 illustrates the execution sequence for a table or list without grouping.

Figure 7-4 Ungrouped table or list detail execution sequence

image

For a table having grouping, BIRT creates one ListingGroup item per group.

A ListingGroup is similar to a table in that it has one or more header rows and one or more footer rows. BIRT processes grouped rows in the same way that it processes a table row.

In addition to the standard onPrepare, onCreate, and onRender events for these rows, the ListingGroup fires the onPageBreak and onPrepare events for the group. To access the script location for these event handlers, locate the group in the outline view and select the script tab. Use code in the onPrepare event handler to modify grouping behavior, such as changing the sort order.

Figure 7-5 illustrates the method execution sequence for a table that has groups.

Figure 7-5 Grouped table execution sequence

image

To verify the execution sequence of event handlers for a specific report, add logging code to the event handlers.

Table and list wrap-up step

The post-table processing step is the same for all tables, both grouped and ungrouped.

Completion of the generation phase

On completion of the generation phase, all data sources, beforeClose and afterClose events fire, followed by the afterFactory event. If using the RunAndRenderTask, the afterRender event fires before closing the data sources. Table 7-10 describes the events available at completion of the generation phase.

Table 7-10 Completing the generation phase

image

Presentation phase operation

The presentation phase launches the appropriate emitter and produces report output based on the generated report. This phase fires the onRender events for all items as they are created. If using the RenderTask to render an existing report document, the initialize event triggers first and then each rendered report item’s onRender event fires.

If the RenderTask renders pages individually, the onRender event fires only for items that are rendered. For example, BIRT Web Viewer uses a RunTask to create a report document. The web viewer uses a RenderTask to render the first page. This action fires the initialize event first and the onRender event for each item that appears on the page. Selecting a new page and using the pagination controls results in a new RenderTask that calls the initialize event again and triggers the onRender event for each item on the new page.

Event order summary

Table 7-11 summarizes the report design and report item events triggered in each processing phase. The events are listed in the order they are fired for a particular task. Page break, getDefaultValueList, getSelectionValueList, data source, and data set events are not shown for brevity.

Table 7-11 Event order summary

image

image

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset