Customize a BIRT-4 document template

Owned by Oksana Vishchuk
Last updated: Oct 02, 2024 by Damian Rozmiarkowski
7 min read

Introduction

Some default document templates available on the XTRF Platform are prepared within the BIRT-4 version. With those templates, you can generate documents, such as invoices or purchase orders, in PDF format. You can also customize the available templates to get a personalized set of documents adjusted to your and your partners' needs. However, this requires getting familiar with the Eclipse environment and having knowledge of incorporating information from the delivered libraries package.

BIRT-4 stands for Business Intelligence and Reporting Tools (BIRT) Luna software project, Release 4.4.0. For more information on BIRT, visit the official Eclipse website.

The delivered XTRF document templates can be adjusted to your requirements in terms of:

  • Information displayed in a document

  • Style of a document.

In the following scenario, you can learn how to set up your Eclipse environment, run your Report Design project, and apply changes to the existing document template.

I. Download the desired document template

  1. Sign in to the XTRF Home Portal.

  2. Go to the Configuration Menu → Templates → Document Templates. 

  3. In the Document Templates view, use the filters on top of the list to locate the BIRT-4 templates.

    1. Set the Built-in Template filter to Yes.

    2. Set the Rendering Engine filter to BIRT 4.

  4. Click the icon to download the desired template and store it on your local machine. The downloaded file is in RPTDESIGN format.

II. Prepare the Eclipse Environment

To work on the document templates and adjust them to your needs, you first need to download the appropriate Eclipse package, unpack it, and set up the Eclipse environment on your local machine.

  1. Download the package and store it on your local machine.

  2. Extract the eclipse-birt4.zip package. The default folder name after unzipping the package is eclipse.

  3. Go to the newly unpacked \eclipse\ folder on your local machine. You should see the files as follows:

  4. Click the eclipse icon to run your Eclipse environment. The Workspace Launcher pop-up window from the Eclipse software project appears.

  5. Select a workspace for your project, for example, yourworkspace, and click OK. The Java EE -Eclipse window appears.

  6. Close the Welcome tab in the Java EE -Eclipse window.

  7. In the top bar, select the Window → Show View → Other.... The Show View pop-up window appears.

  8. In the explorer tree of the Show View pop-up window, select the Report Design → Property Editor subbranch and click the OK button.

Now you can work in your Eclipse environment:

III. Run your Report Design project

In Eclipse, you can use project perspectives to structure your files and simultaneously have access to project management tools. It lets you conveniently edit the selected document template and simplify the deployment process. In this section, you will learn how to prepare your desired document template for customization within the Report Design perspective.

  1. In the Java - Eclipse window, select the File → New → Project. The New Project pop-up window appears.

  2. In the New Project pop-up window, perform the following steps:

    1. In the explorer tree, select the Business Intelligence and Reporting Tools > Report Project subbranch.

    2. Click the Next button. You are redirected to the Report Project display.

    3. In the Project name field, provide the name of your project, for example, Document Templates.

    4. Uncheck the Use default location box - it enables you to define the location of your report project.

    5. Click the Browse button. The file manager window available on your local machine appears.

      1. Select the directory where the document template downloaded in step I was saved.

      2. Click the Ok button. The file manager window closes.

    6. The selected location of the files appears in the Location field in the Report Project display.

    7. Click the Finish button. The New Project pop-up window closes.

Open Associated Perspective pop-up window

It might happen that when the New Project pop-up window closes, the Open Associated Perspective? pop-up window appears, asking you if you want to open the perspective at this moment. Click the Yes button to continue opening your report project.

You have just opened the report project in Eclipse.

IV. Edit the document template

When your Eclipse environment is set up, you can modify both the content of displayed information and the layout of the document template.

To access the required document template in the editable format in the Eclipse project:

  1. Go to the Navigator panel in the bottom left-hand corner of the Eclipse environment.

  2. Select the document template you are about to modify. In this guide, the CustomerQuoteConfirmation.rptdesign file is selected.

You can now modify the selected document template using settings delivered within Eclipse.

IV.I. Modify the content of your document template

To personalize the content of the document template, you can use the embedded *.rptlibrary libraries. Each document template encapsulates particular libraries, which enables you to simply drag and drop an item to add it to the report. First, you need to know which libraries are used for each template; next, you can use the report items available in the known libraries to change the content of a given document template. The following steps show how to add a report component to the Customer Quote Confirmation document template.

Document templates common library

Each document template downloaded from XTRF encapsulates the commonLib.rptlibrary file. You can use the report items delivered within this library in each document template.  

  1. Click the XML Source tab. You can see the document template as the .XML file. 

  2. Find the libraries property in the given DocumentTemplate.rptdesign file. You can find out which libraries are encapsulated for the document template. In this guide, the CustomerQuoteConfirmation.rptdesign file is given as an example: you can see that the following libraries are added:

    • The projectConfirmationLib.rptlibrary file

    • The commonLib.rptlibrary file.

 CustomerQuoteConfirmation.rptdesign

<list-property name="libraries"> <structure> <property name="fileName">libs/1.0.13/projectConfirmationLib.rptlibrary</property> <property name="namespace">projectConfirmationLib</property> </structure> <structure> <property name="fileName">libs/1.0.13/commonLib.rptlibrary</property> <property name="namespace">commonLib</property> </structure> </list-property>

  1. In the Resource Explorer tab, expand a given *.rptlibrary file, for example, the commonLib.rptlibrary.

  2.  In the Resource Explorer tab, expand the Report Items subbranch. For example, you can see the report components embedded in the commonLib.rptlibrary file.

  3. Select the report component from the Report Item subbranch: drag and drop it into the displayed document template.

  4. In the Report Design menu, select File > Save to store all changes you have made in the document template.

IV.II. Modify the document template properties

Modifying the document template properties means changing the layout of the template. You can do it on the spot using the settings available in the Eclipse environment. The following steps instruct you how to find the settings used to change the design of the document layout:

  1. Go to the Property Editor tab at the bottom of the selected document template Report Design window.

  2. In the Properties tab, you can find the list of all properties used to adjust the document template to your needs.

  1. Make the necessary changes.

  2. Select File → Save in the Report Design menu.

V. Upload the customized document template

To learn how to upload a BIRT-4 document template, see the Add a BIRT-4 document template | II. Upload a document template article.

Â