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 Together

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

BIRT Report Editor View

The BIRT Report Editor View (as shown in Figure 1) 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 Tab Function

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

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

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

BIRT Data Explorer View

Before building a report, you will need access to data. The Data Explorer view (Figure 3) 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 MongoDB/Cassandra 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 source.


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

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

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 Variable 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 5) 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 highlighting. 
  • 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 element.
  • 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 filtering.
  • 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 View

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

Author Bio:

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

Inline Feedbacks
View all comments