Smarten up your data again!

Tutorial: Eclipse BIRT Designer Perspective


On Tuesday, we were introduced to the BIRT engine pipeline. This time round, Jason Weathersby and Ray Gans look at each of the Eclipse Views that make up the BIRT Designer Perspective.

On Tuesday
, we were introduced to the BIRT engine pipeline.
This time round, Jason Weathersby and Ray Gans look at each of the
Eclipse Views that make up the BIRT Designer Perspective. This
article previously appeared in JAX Magazine:Pulling

The BIRT Designer Perspective is constructed using a set of
Eclipse Views. These Views are the Outline, Palette, Report Editor,
Data Explorer, Resource Explorer, and Property Editor. Each of
these Views is explained and detailed in the following

BIRT Report Editor View

The BIRT Report Editor View (as shown in Figure
) represents the canvas where report items are placed and
configured. This view contains several tabs across the bottom of
the editor. Table 1 details the function of each of the tabs.

Figure 1: Report Editor
Report Editor

 The Layout Tab functions as the report canvas and also
supports drag and drop from the palette and the resource

Master Page  BIRT supports creating one or more master pages for a
report. The master page is used to configure content on a page
basis and supports headers, footers, margins, sizes, and
orientation. In addition multiple master pages can be used within a
report and assigned to specific report items. For example one table
in a report may be displayed in portrait mode while another may be
displayed in landscape. The Master Page tab allows the developer to
edit one or more master pages.
 Script  The Script tab opens the BIRT JavaScript editor for a
selected report item. See event handling in part 1 of this article

 XML Source

This view displays the actual generated XML for the current
report. The XML can be modified as well. This view will also supply
a red x icon next to lines within a report that are currently in
 Preview  This tab allows the current report to be previewed. The
report can also be previewed from the toolbar, as shown in
Figure 2, allowing the developer to see what the
report will look like in a specific output format.


Figure 2: Report Toolbar

BIRT Data Explorer View

Before building a report, you will
need access to data. The Data Explorer view (Figure
) is used to construct data sources and data sets, which
represent connections to a specific data source type and a tabular
set of data, which is returned from the data source. A data set
returns a tabular list consisting of rows and columns much like a
result set of a SQL query. 

Figure 3: Data Explorer View

BIRT currently supports JDBC (textual and graphical), Web Services,
XML, Flat File, Excel, and Hive/Hadoop data sources (Editor’s
Note – and now
 in newest version

In addition BIRT supports a scripted
data source that allows the user to develop a custom data source,
using JavaScript or Java to return data results. The properties for
these data sources can also be customized at runtime using a
feature called Property Binding built with the Expression Builder
or with the use of a simple JavaScript event handler.

In both cases, the property is set
with a small amount of JavaScript. For example, to change the
database URL of a JDBC data source in a report, the following
JavaScript could be used in the beforeOpen event of a JDBC data


extensionProperties.odaURL = "jdbc:mysql://localhost/"+params{“mydbparameter”];


When building a data source, the
developer also has the option to create the connection from an
externally stored profile. This allows connection credentials to be
managed separately from the report design. 

Developers can extend and create new
BIRT data sources using extension points provided by the Data Tools
Project. These extension points not only provide extensions to the
data access engine but also allow developers to create custom GUIs
that the BIRT designer will launch. Once developed these new data
sources can be easily deployed to any BIRT designer. Many examples
of these custom data sources (ODA –Open Data Access) drivers are
available at BIRT

The Data Explorer View also allows the
creation of data cubes. Cubes (shown in Figure 4)
analyze complex hierarchical data but can also be used in
conjunction with charts and the crosstab report element. BIRT data
cubes are multi-dimensional cubes, based on one or more BIRT
datasets, constructed using the Data Cube Builder. BIRT Cubes
support dimensions –static and dynamic, measures, derived measures
and filters.

Figure 4: BIRT Data Cubes

We’ll cover more details on the crosstab and chart report elements
within the Palette View section.

BIRT provides two types of parameters
Report Parameters and Data Set
. Report parameters are global to the
report and are generally exposed to the end user.

Data Set Parameters differ in that
they are used to make Data Sets more dynamic, and are not generally
exposed to the end user. Data Set Parameters can be linked
within the Data Set Editor to Report Parameters or set using script
or expressions. Report parameters are created in the Data Explorer
View and are often used to personalize the report for a given user.
Report parameters for example, can be tied to Data Set Parameters
to modify a query, used in a BIRT JavaScript expression to change
the style and visibility of a report element. They can also be used
within a script event to personalize the content based on the
selected output format. 

Report parameters can be static or
dynamic. Static parameters are parameters that allow the user to
select from a predefined set of values or to enter a desired value,
for example, in a text box. Dynamic parameters are parameters that
can be data bound to an existing BIRT data set. For example, a user
may select a customer from a list of customers provided by a data
set. Dynamic parameters can also be scripted to allow the developer
to decide which values will be displayed to the end user. 

In addition, BIRT supports cascading
parameters that allow multiple list/combo boxes to be displayed
with each subsequent selection list being modified by previously
selected values. So, a cascaded parameter could present an alpha
list in the first list box and the customer names starting with the
selected alpha character in the second list box. Cascaded
parameters can be created using one or more BIRT Data

The Variables node of the Data
Explorer view is used to create a special type of pagination
variable which can be one of two types: Report
or Page Variable

Report Variables are evaluated when
the report is complete while Page Variables are evaluated at the
time a page is created. Either type can be placed on the master
page by selecting the Palette View and selecting the Variable
AutoText field when using the master page editor. While these page
variables can be accessed by Expressions and JavaScript their main
use is when creating page specific calculations. For example,
creating a page n of m for specific groups within a report. These
variables are generally set using page script event handlers
(onPageStart and onPageEnd events). 



The BIRT Palette View (Figure
) lists all report items that can be used to construct a
report. The Palette contains some items that are used to layout the
structure of the report, like grids, and other items that are bound
to data, like tables and charts.

Figure 5: Palette

The palette supports the following
report items.

  • Label elements are used for displaying static
    text. Label elements support localization, hyperlinks and
  • Text elements are used to display static and
    dynamic text, including the ability to handle multi-line and
    formatted HTML content. Values from existing data sets, parameters,
    JavaScript functions, and BIRT script functions can also be
    injected into the formatted HTML using the BIRT Expression Builder.
    The element can also be used to create scripts that are executed on
    the client side by using the <script> tag.
  • Dynamic text elements are used to display CLOB
    data values.
  • Data elements are the primary element for
    displaying values from data sets. The value displayed in a data
    item will be determined by the expression attached to the element
    and most often contains one or more data set columns. For example
    an expression for customer contact may look like:


dataSetRow["contactLastName"] + ", " + dataSetRow["contactFirstName"] 


  • Image elements are used to include both static
    and dynamic images within a report. BIRT supports retrieving images
    from a URI, embedding the image in the design (Base64 encoded),
    dynamic images (BLOB) from a data source, and image files in a
    resource folder. Each of these image types can also be customized
    using scripting. For example a resource folder image can be changed
    using an onCreate script similar to the following example.


var myqty = this.getRowData().getColumnValue("QUANTITYORDERED");
if( myqty > 30 ){
        this.file = "green.png";
}else if( myqty > 25 && myqty <= 30){
        this.file ="yellow.png";



  • Grid elements are the main layout component
    within BIRT. They allow a developer to layout sections within a
    report in logical order using static rows and columns. Dynamic
    items such as charts and tables are using nested within a grid
  • List elements iterate over data sets that are
    bound to the list. The default list element has a header, footer
    and detail section. The header and footer are displayed once, while
    the detail section is evaluated once for every row of the data set
    that is bound to the list. Lists are one column tables. List
    elements also support grouping, mapping, sorting, highlights, and
  • Table elements act much like a List element
    but support multiple headers, footers, and detail rows.  In
    addition Table elements support multiple columns. Tables also
    support grouping, mapping, sorting, highlights, and filtering.
  • Aggregation elements provide functionality to
    add aggregate data across lists, tables, cross tabs, and groups.
    The Aggregation Builder supplies thirty different functions such as
    SUM, MIN, MAX, VARIANCE, MIRR and AVERAGE. This element also
    supports total aggregation or group aggregation for tables and
    lists. Aggregated data can also be filtered.
  • The chart element is used to add charting to a
    report. BIRT provides a three tabbed wizard to configure charts
    (Select Chart Type, Select Data, and Format Chart). Fourteen
    primary chart types and many combinations of sub-types are
    available. Chart elements can be presented in PNG, JGP, BMP, and
    SVG output, and support many interactive features including drill
    through and client side scripting. Charts can source data from BIRT
    data sets, cubes, container elements, or from another report item
    within the report. The Chart Wizard in Figure 6
    demonstrates what can be edited.
Figure 6: Chart Wizard


  • The Cross Tab element can be used to visualize
    data contained within a BIRT data cube. The cross tab element does
    not have a fixed number of columns or rows. The number of each is
    determined by the data retrieved from the data cube. This element
    supports hierarchical aggregation and display of data.
  • Cube dimensions are placed on rows and
    columns, and aggregated measure data is calculated at the
    designated intersections. It also supports derived measures, group
    and grand totals, column and row totals, filtering and
    highlighting. In addition, the cross tab element supports
    representing measures with a chart, like in Figure 7. Using
    parameters and scripts cross tabs can be very dynamic and provide
    highly interactive visualizations of data.
Figure 7: Chart Report Item
  • The Relative Time Period report item is used
    within cross tabs to calculate time based values relative to the
    current time dimension. This report item supports thirteen relative
    time periods which include functions like Quarter to Date, Period
    to Date, Current Quarter and Next N Periods.

Property Editor

The Property Editor View
(Figure 8) is used to set design-specific
properties for elements that have been added to the report. The
properties displayed are those available for the specific report
item type and will vary. In general most report items will have
font and sizing information, localization keys, visibility
expressions, hyperlink fields, and table of contents entries. Bound
items will contain a tab for binding the report item to a dataset,
in addition to grouping, sorting and filtering tabs. 

BIRT also contains a mapping feature
where data can be displayed differently depending on an expression.
For example, if a data item for week day returns a ‘2’ you could
use the mapping feature to display either ‘Monday’ or ‘Tuesday’.
Most items also support Highlights, which allow style properties or
custom styles to be applied to a report item based on some data
value or expression. 

Figure 8: Property Editor

The Sorting tab uses BIRT expressions
to apply specific sorting orders. BIRT provides sorting on many
report items, such as tables, charts, group sections, and
crosstabs. Sorting includes the ability to create a custom sort
order as well as setting the collation strength and locale.

Resource Explorer View

BIRT uses a resource folder for
storing images, properties files, external global JavaScript
functions, jar files and report libraries. The resource folder
works as a common area for a project to share virtually any content
across reports. When the Web Viewer is deployed the resource folder
is configurable within the web.xml for the application. The
Resource Explorer View (Figure 9) is used to
navigate the current resource folder, which can be configured
globally or on a project basis. Report items that have been placed
in a library can be explored using this View. The Resource View
supports drag and drop functionality, allowing items that have been
placed in a library to be used in any report.

Figure 9: Resource Explorer

Outline View

The Outline View presents a graphical
node view of the hierarchy of a report design. This View can be
used to select any item within the report and is useful when
reports contain many nested report items. This view can also be
used to import styles, link to external styles, embed images, link
libraries to the report, and easily access any scripts that exist
within the report.


In this article we detailed each of
the Views that make up the BIRT Report Designer Perspective. For
more information on other aspects of the project or for details on
contributing please visit the BIRT website


Jason Weathersby was the BIRT
Evangelist at Actuate Corporation and a member of the Eclipse
Business Intelligence and Reporting Tools (BIRT) Project Management
Committee (PMC). He now works at Mozilla.

Ray Gans is the Community Manager
for BIRT Exchange at Actuate Corporation where, as chief liaison
between BIRT developers and the company, he is responsible for
building relationships with the BIRT developer and user
communities. His goals are to drive collaboration between BIRT
users to share ideas, knowledge and experiences with each other;
build user groups; and monitor the community to help ensure its
vitality and growth. Previously, at Sun Microsystems, Ray co-led
the team responsible for moving Java SE into open source and was
Java Program Manager before that at Apple.

This article appearing JAX
Magazine: Pulling Together

Jason Weathersby was previously the BIRT Evangelist at Actuate Corporation and a member of the Eclipse Business Intelligence and Reporting Tools (BIRT) Project Management Committee (PMC). He is now the Technical Evangelist at Technical Evangelist at Mozilla Corporation
comments powered by Disqus