Introduction

For many people, BIRT (Business
Intelligence and Reporting Tools) may be
only a reporting tool. But in fact, the real strength of
BIRT is not only its built-in reporting functionality, but also
its
extension capabilities. Using extensions, a user can easily extend the
functionality of BIRT, creating custom extended report items, adding custom
emitters, and even having custom editor pages. The power of extensions
enables the user to create
custom reporting features that can meet very specific requirements. In
this
article, we explore how to leverage the BIRT extension mechanism to
extend the BIRT capabilities. The provided samples
cover most of the essential extension points that provided by BIRT report
model, engine and designer.

This article assumes the reader already has the knowledge about the Eclipse extension mechanism.
If you are not familiar with that, you can read this article first about the
Eclipse Plug-in Architecture to get some initial concept.

This article also uses an Eclipse plug-in project to hold all the source code and demonstrate the extension mechanism.
You can either import the project directly from this archive or create your
own plug-in project through the Eclipse IDE.

The Basics

BIRT already contains the basic Label and Text report items,
but these items can only show horizontal text. Sometimes, user
would
like to show angled text; in this case, alternative solution is needed.
In the following sections, we introduce how to implement a
RotatedText
extended report item through BIRT extensions, and how to enhance
the functionality step-by-step by implementing more extension points.

Note: This example is a modified version based
on the RotatedText sample on BIRT CVS, the original code
can be retrieved from Eclipse CVS.

To implement an extended report item, we need look at the following extension points:

org.eclipse.birt.report.model.reportItemModel

org.eclipse.birt.report.designer.ui.reportitemUI

org.eclipse.birt.report.engine.reportitemPresentation

These three extensions provide the basics to implement an extended
report item. In brief,
org.eclipse.birt.report.model.reportItemModel provides the report
model extensibility, org.eclipse.birt.report.designer.ui.reportitemUI
provides the report designer extensibility, and
org.eclipse.birt.report.engine.reportitemPresentation provides the
report engine extensibility.

org.eclipse.birt.report.model.reportItemModel

This extension point is provided by the BIRT Report Model. Normally the user
uses this extension point to define the extended report item model.

First we need define a new report item model
extension. To achieve this, we create a "reportItem" element under the extension and specify the extensionName property as "RotatedText".
The extension name is the identifier
for the extended item, it's also the only symbol that connects between the report model
and engine/designer extensions.

Then we define the model factory class as
org.eclipse.birt.sample.reportitem.rotatedtext.RotatedTextItemFactory.
This factory class will be used to create and initialize the
IReportItem instance, as well as providing optional localization support:

From the "reportItem" properties page, we can see some other settings like "defaultStyle", "extendsFrom", etc.
They can be used to control more capabilities of the extended item. As we are not using them in this example,
we just omit them here.

Here we define two new properties for the RotatedText extended report item:

rotationAngle, the rotation angle, integer type, default as 0.

text, the text content, string type, default as "Rotated Text".

We can see in the properties page there are also some settings that we didn't touch. Normally they are for more complex property types and
are out of the scope of this article, so we just omit them here.

Once we completed the model definition, we need give a IReportItem
implementation. This class is used to encapsulate the extended report
item model, and providing some convenient property accessing APIs:

We can see most of the methods here are just getter/setters. For
a simple extended report item, this is normally enough.

org.eclipse.birt.report.designer.ui.reportitemUI

This extension point is provided by BIRT Designer, the user uses this
extension point to define the UI behavior for extended report
items.

First we need create a "model" element under the extension. This is to bind the Designer extension with the Model extension. To do
this, we specify the extensionName property as "RotatedText", which exactly matches the model extension name.

The next step, we create some other elements like "palette", "editor" and "outline" under the extension, and specify the detailed settings for this extended report item as following:

Palette specifies the icon to be shown in Palette view, as well as the
palette category. If the category is not specified, the default "Report Items" category will be used.

Editor specifies the report item visibility in different editor pages, and whether the resizing control is enabled.

Outline specifies the icon to be shown in Outline view. Normally this is the same as the one in Palette view.

The last step, we need specify the UI provider for this extended report item.

The UI provider defines how to display and interact with the
extended report item within the editor. BIRT designer support three types of
basic UI providers:

The Label UI Provider implements the IReportItemLabelProvider interface, which simply manipulates and displays a text content.

The Image UI Provider implements the IReportItemImageProvider interface, which simply manipulates and displays an image content.

the Figure UI Provider implements the IRportItemFigureProvider, which uses the Figure interface from GEF, providing more flexibility and interactivity support.

In this example, we choose to implement the simplest Label UI
Provider first, in subsequent examples, we will introduce other types of UI providers.

To register the Label UI provider, we create a "reportItemLabelUI" element under the extension, and specify the implementor class, which must implement IReportItemLabelProvider interface.

You can see that what it does is to read the text property value from the model and return it as a string.

After we completed the designer extension, we can run the designer and check what we have:
the Palette view now contains the new RotatedText extended report item.

If you right-click anywhere in the editor, you can see the RotatedText item is
also available in the "Insert" context menu.

When you insert one RotatedText item into the layout, it appears in the Outline view.

Select the RotatedText item, and open the Properties view. It immediately
lists all the properties that belong to this extended report item. Among
them, we can see the "Rotation Angle" and "Text
Content" as well as other inherited properties. The user can edit these
property values through this view.

Now that the designer extension is done, we'll continue to the Report Engine extension.

org.eclipse.birt.report.engine.reportitemPresentation

This extension point is provided by BIRT Report Engine, the user uses
this extension point to define the presentation behavior of the
extended report item.

First we bind the engine extension with the model extension. To achieve this, we create a "reportItem" element under the engine extension and
specify the name property as "RotatedText", also we specify the presentation implementor class
as org.eclipse.birt.sample.reportitem.rotatedtext.RotatedTextPresentationImpl.
The presentation implementor class must implement the
IReportItemPresentation interface.

Our plan for implementing the rotated text effect is to create an image
dynamically, in this image, we use Swing graphics API to render the
rotated text.