Chapter 22. Developing a Fragment
The BIRT Report Engine environment supports plug-in fragments. A plug-in fragment is a separately loaded package that adds functionality to an existing plug-in, such as a specific language translation in a National Language Support (NLS) localization application.
The Eclipse Babel Project provides language packs that support the translation of strings in the Eclipse user interface. For BIRT, the Babel Project provides an NLS plug-in for most major languages. For more information about the Babel Project and to download language packs, navigate to:
http://babel.eclipse.org/babel/
The example in this chapter creates a Java resource bundle that adds translations to the messages defined in the messages.properties files for the org.eclipse.birt.report.viewer plug-in.
Understanding a fragment
A fragment does not define its own plugin.xml file or a plug-in class. The related plug-in controls all processing. A fragment loads along the classpath of the related plug-in, providing access to all classes in the plug-in package.
A fragment inherits all the resources specified in the requires element of the plug-in manifest. A fragment can also specify additional libraries, extensions, and other resources.
The fragment’s optional manifest file, fragment.xml, contains the attributes that associate the fragment with the plug-in. A fragment.xml file can specify the following tags and associated attributes:
• <fragment>
Specifies the following attributes:
• name
Display name of the extension.
• id
Unique identifier for the fragment extension.
• plugin-id
The plug-in associated with the fragment.
• version
Version of the fragment extension, such as 2.6.0.
• type
Specification of a code or a resource file contained in the fragment. The default is code.
• <runtime>
Specifies a list of one or more libraries required by the fragment runtime. The name attribute for the <library> element can specify an archive, directory, or substitution variable.
Developing the sample fragment
The fragment example in this chapter creates an XML specification that loads additional messages.properties files that contain the translations of messages in the resource bundle for the org.eclipse.birt.report.viewer plug-in. This section describes the steps required to implement the sample org.eclipse.birt.report.viewers.nl1 project, using the Eclipse Plug-in Development Environment (PDE).
To implement the sample fragment, perform the following tasks:
• Configure the fragment project.
To build the sample fragment plug-in project, follow the instructions in this chapter.
• Add the translations contained in the message properties files to the org.eclipse.birt.report.resource bundle.
The name of each message properties file uses the following pattern:
Messages_<lower-case language symbol>.properties
For example, Messages_es.properties indicates the message properties file for Spanish (Español).
• Build, deploy, and test the fragment.
Build the fragment and export the fragment package from your workspace to the eclipseplugins folder. Test the fragment by starting Eclipse using a specific language setting and creating a report in the BIRT report designer.
Creating a fragment project
You can create the fragment project for the NL1 fragment sample in the PDE.
How to create the fragment project
1 In the Eclipse PDE, choose File→New→Project.
2 In New Project, in Select a wizard, expand Plug-in Development and select Fragment Project. Choose Next. New Fragment Project appears.
3 In Fragment Project modify the settings, as shown in Table 22-1.
Table 22-1 Settings for Fragment Project fields
Fragment Project appears, as shown in Figure 22-1. Choose Next.
Figure 22-1 Fragment Project settings
4 In Fragment Content, modify the settings as shown in Table 22-2.
Table 22-2 Fragment Content settings
Fragment Content appears, as shown in Figure 22-2. Choose Finish.
Figure 22-2 Fragment Content settings
The fragment project appears in the Eclipse PDE Workbench, as shown in Figure 22-3.
Figure 22-3 Fragment project in the Eclipse PDE Workbench
Understanding the sample fragment
The fragment provides the functionality required at run-time to display the messages seen in the BIRT Report Viewer in alternative languages. The fragment implements NLS messages.properties files in org.eclipse.birt.report.resource.
Listing 22-1 shows an excerpt from the Spanish language version of BIRT Report Viewer messages from the file, Messages_es.properties.
Listing 22-1 Contents of Messages_es.properties
##############################################################
birt.viewer.title=BIRT Report Viewer
birt.viewer.title.navigation=Navegación
birt.viewer.title.error=Error
birt.viewer.title.complete=Completado
birt.viewer.title.message=Mensaje
birt.viewer.parameter=Parámetro
birt.viewer.runreport=Ejecutar informe
birt.viewer.required=Los parámetros marcados con
<FONT COLOR="red">*</FONT> son obligatorios.
birt.viewer.viewinpdf=Ver en PDF
birt.viewer.maximize=Ocultar parámetros de informe
birt.viewer.restore=Mostrar parámetros de informe
birt.viewer.error=Mensaje de error
birt.viewer.error.noparameter=No hay ningún parámetro para este
informe.
birt.viewer.error.parameter.invalid=El parámetro"{0}" no es
válido.
birt.viewer.error.noprinter=No se puede encontrar ninguna
impresora disponible compatible con el formato postscript.
birt.viewer.error.unknownerror=Error desconocido.
birt.viewer.error.generatereportfirst=Se debe generar antes un
documento de informe.
birt.viewer.error.parameterrequired=No se ha especificado el valor
del parámetro necesario [{0}].
birt.viewer.error.parameternotallowblank=El parámetro "{0}" no
puede estar en blanco.
birt.viewer.error.parameternotselected=Seleccione un valor para el
parámetro"{0}".
birt.viewer.error.noviewingsession=La sesión de visualización no
está disponible o ha caducado.
birt.viewer.error.viewingsessionexpired=La sesión de visualización
ha caducado.
birt.viewer.error.viewingsessionlocked=La sesión de visualización
está bloqueada y no se puede finalizar.
birt.viewer.error.viewingsessionmaxreached=Se ha alcanzado el
máximo de sesiones de visualización.
birt.viewer.message.taskcanceled=La operación en proceso se ha
cancelado.
##############################################################
# Toolbar
##############################################################
birt.viewer.toolbar.print=Imprimir informe como PDF
birt.viewer.toolbar.printserver=Imprimir informe en el servidor
birt.viewer.toolbar.toc=Mostrar tabla de contenido
birt.viewer.toolbar.parameter=Ejecutar informe
birt.viewer.toolbar.export=Exportar datos
birt.viewer.toolbar.font=Cambiar fuente
birt.viewer.toolbar.enableiv=Llamar a Interactive Viewer
birt.viewer.toolbar.exportreport=Exportar informe
...
Building, deploying, and testing a fragment
Build the fragment after generating and modifying the build.xml file to specify the conversion of .msg files from native to ASCII format as .properties files. Listing 22-2 shows the contents of the build.xml file with the NativeToAscii specification.
Listing 22-2 Contents of build.xml file
<?xml version="1.0" encoding="UTF-8"?>
<project
name="org.eclipse.birt.report.viewer.nl" default="Jar"
basedir=".">
<description>
NL Fragment for org.eclipse.birt.report.viewer
</description>
<property file="META-INF/MANIFEST.MF" />
<property name="dir.src" value="src" />
<property name="dir.bin" value="bin" />
<property name="nl.group" value="1" />
<property name="module.name"
value="org.eclipse.birt.report.viewer.nl" />
<property name="jar.name"
value=
"${module.name}${nl.group}_${Bundle-Version}.jar" />
<target name="Clean">
<delete>
<fileset dir="${dir.src}"
includes="**/*_??_??.properties" />
<fileset dir="." includes="${jar.name}" />
</delete>
</target>
<target name="NativeToAscii"
description="Execute native2ascii for *.msg files">
<native2ascii encoding="Cp1252"
src="${dir.src}"
dest="${dir.src}"
ext=".properties"
includes="**/*_de_DE.msg,
**/*_fr_FR.msg, **/*_es_ES.msg"/>
<native2ascii encoding="GBK"
src="${dir.src}"
dest="${dir.src}"
ext=".properties"
includes="**/*_zh_CN.msg"/>
<native2ascii encoding="SJIS"
src="${dir.src}"
dest="${dir.src}"
ext=".properties"
includes="**/*_ja_JP.msg"/>
<native2ascii encoding="MS949"
src="${dir.src}"
dest="${dir.src}"
ext=".properties"
includes="**/*_ko_KR.msg"/>
</target>
<target name="nl-jar">
<jar destfile="${jar.name}"
manifest="./META-INF/MANIFEST.MF">
<zipfileset dir="${dir.src}"
includes="**/*.properties"/>
<fileset dir="."
includes="plugin_??_??.properties"/>
</jar>
</target>
<target
name="Jar" depends="NativeToAscii, nl-jar" >
</target>
<target name="Export">
<copy todir="${export.dir}">
<fileset dir="." includes="${jar.name}"/>
</copy>
</target>
</project>
If you set the fragment version number to 2.6.0.qualifier, the Eclipse PDE generates a JAR file with the following name:
org.eclipse.birt.report.viewer.nl1_2.6.0.qualifier.jar
Before building the fragment, change qualifier to the BIRT Report Viewer plug-in build number, such as v20100605. The Eclipse PDE generates a JAR file with the following name:
org.eclipse.birt.report.viewer.nl1_2.6.0.v20100605.jar
The Eclipse PDE provides support for deploying the plug-in in a run-time environment. To deploy the fragment to the BIRT Report Viewer example, use the Export wizard as shown in Figure 22-4 or manually copy the org.eclipse.birt.report.viewer.nl1 JAR file from your workspace to the eclipse/plugins folder.
Figure 22-4 Deploying a fragment using the Export wizard
Test the fragment after deploying it by starting Eclipse using the -nl argument with the desired language setting. Listing 22-3 shows the command to start Eclipse using the -nl argument with the lowercase symbol for Spanish, as specified in the name of the Spanish messages.properties file, Messages_es.properties.
Listing 22-3 Starting Eclipse using the -nl setting for Spanish
eclipse -nl es
In Eclipse, open BIRT Report Designer, or in Spanish, Diseño de informe perspective, as shown in Figure 22-5.
Figure 22-5 Opening the BIRT perspective using Spanish NL1 settings
The BIRT Report Designer appears with the Spanish language settings specified in the NL1 language pack. Figure 22-6 shows the Palette with the names of the report items appearing in Spanish.
Figure 22-6 The Palette using Spanish NL1 settings
Figure 22-7 shows the Property Editor with the names of the Properties categories and the settings for General appearing in Spanish.
Figure 22-7 The Property Editor using Spanish NL1 settings
Run the report using BIRT Web Viewer by choosing View Report→View report in Web Viewer or, in Spanish, Ver informe en Web Viewer, as shown in Figure 22-8.
Figure 22-8 Running a report in Web Viewer using Spanish NL1 settings
Figure 22-9 shows the Editor with the names of the Editor tabs appearing in Spanish.
Figure 22-9 The Editor using Spanish NL1 settings
Figure 22-10 shows the report with the BIRT Web Viewer page prompts, such as Showing page appearing in Spanish as Mostrando página.
Figure 22-10 The Web Viewer using Spanish NL1 settings
The NLS language pack configures only elements in the BIRT Report Designer and Viewer user interfaces. For example, in Figure 22-9 and Figure 22-10, the elements in the report design and output, such as the table title and column names, are user-defined and not part of the NL1 language pack configuration.