ODTReportingQuickStart
Since XDocReport 0.9.5 provides XDocReport Tools and you can design your ODT report with OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt. This section explains how to :
- design a ODT report with OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt.
- preview the generated OTD report with this macro .
- integrate your ODT report in a Java Main by replacing text-input with values coming from Java model.
The OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt helps you to design the ODT report, but it is not required to generate ODT reporting in your Java application. This macro is very useful to design ODT report but it doesn't manage advanced reporting (like if condition, complex loop).
We suggest to read ODT Reporting section for more explanation about ODT reporting to know which JARs you must use (Maven is adwiced for instance).
In this section we will design the following ODT report by using the OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt macro :
We will preview with OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt macro and generate with Java main this ODT :
Since XDocReport 0.9.5, XDocReport provides Tools that you can download in the Zip fr.opensagres.xdocreport.document.tools-xxx-distribution.zip. This zip contains 3 folders :
- bin : which contains the bat file xdrtools.bat and sh file xdrtools.sh which is required for the preview fetaure of the macro. This bat/sh file calls XDocReport JARs from the lib folder.
- lib : which contains the whole JAR required to generate ODT report with Freemarker or Velocity syntax.
- macro : which contains the OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt macro.
Download this zip, and unzip it in a folder (in this section, zip is unzipped to C:\XDocReport):
Create a Java Project with your favorite IDE and copy/paste the JARs from the lib folder (coming from the zip) to your Java Project and add JARs in your classpath. In this section xdocreport-quickstart-odt Eclipse Java project is created :
Create your Java model classes. In this section we will create Project and Developer model. Create fr.opensagres.xdocreport.quickstart.model.Project class like this:
package fr.opensagres.xdocreport.quickstart.model;
public class Project {
private final String name;
public Project(String name) {
this.name = name;
}
public String getName() {
return name;
}
}Create fr.opensagres.xdocreport.quickstart.model.Developer class like this:
package fr.opensagres.xdocreport.quickstart.model;
public class Developer {
private final String name;
private final String lastName;
private final String mail;
public Developer(String name, String lastName, String mail) {
this.name = name;
this.lastName = lastName;
this.mail = mail;
}
public String getName() {
return name;
}
public String getLastName() {
return lastName;
}
public String getMail() {
return mail;
}
}The OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt macro needs XML fields. You can generate it from the Java model. Create the fr.opensagres.xdocreport.quickstart.GenerateXMLFields class like this:
package fr.opensagres.xdocreport.quickstart;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import fr.opensagres.xdocreport.core.XDocReportException;
import fr.opensagres.xdocreport.quickstart.model.Developer;
import fr.opensagres.xdocreport.quickstart.model.Project;
import fr.opensagres.xdocreport.template.TemplateEngineKind;
import fr.opensagres.xdocreport.template.formatter.FieldsMetadata;
public class GenerateXMLFields {
public static void main(String[] args) throws XDocReportException,IOException {
// 1) Create FieldsMetadata by setting Velocity as template engine
FieldsMetadata fieldsMetadata = new FieldsMetadata(TemplateEngineKind.Velocity.name());
// 2) Load fields metadata from Java Class
fieldsMetadata.load("project", Project.class);
// Here load is called with true because model is a list of Developer.
fieldsMetadata.load("developers", Developer.class, true);
// 3) Generate XML fields in the file "project.fields.xml".
// Extension *.fields.xml is very important to use it with MS Macro XDocReport.dotm
// FieldsMetadata#saveXML is called with true to indent the XML.
File xmlFieldsFile = new File("project.fields.xml");
fieldsMetadata.saveXML(new FileOutputStream(xmlFieldsFile), true);
}
}If you run the Java main and you refresh your Eclipse Project, project.fields.xml is generated:
Here the content of the project.fields.xml :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<fields templateEngineKind="Velocity" >
<description><![<field name="project.Name" list="false" imageName="" syntaxKind="">
<description><![CDATA[]](CDATA[]]></description>)></description>
</field>
<field name="developers.LastName" list="true" imageName="" syntaxKind="">
<description><![</field>
<field name="developers.Mail" list="true" imageName="" syntaxKind="">
<description><![CDATA[]](CDATA[]]></description>)></description>
</field>
<field name="developers.Name" list="true" imageName="" syntaxKind="">
<description><
Click on OK button and accept the license :
This action will install the XDocReport extension :
Close OpenOffice/LibreOffice and reopon it. If installation was done with no errors, you will see the new XDocReport menu :
The configuration of the OOo Extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt must be done for :
- using the XML fields dialog which help you to insert quickly the text-input of your model.
- preview the result of the merge between the designed ODT and values (coming from JSON data file).
The fields dialog display in a treeview the fields coming from xxx.fields.xml files. You must configure the directory which contains those files. In our case we have one file project.fields.xml in our Eclipse Project xdocreport-quickstart-odt. Click on Settings menu :
and select the directory which contains the project.fields.xml and click on Save button. If the directory is correct, you will see this message:
If you click on Fields menu :
the fields dialog opens and treeview is populated with fields coming from the project.fields.xml :
Since XDocReport 0.9.5, XDocReport provides the capability to generate a report with Java command by calling fr.opensagres.xdocreport.document.tools.Main class. The preview feature uses this Java command by calling the xdrtools.bat (if your OS is Windows) or xdrtools.sh (if your OS is Linux) which call fr.opensagres.xdocreport.document.tools.Main.
So you must select the xdrtools.bat file or xdrtools.sh according your OS. To do that, click on Settings menu :
and *select the xdrtools.bat or xdrtools.sh according your OS and click on Save button. If the selected file is correct, you will see this green message:
Open the Fields Dialog with XDocReport->Fields menu. Now you can design your ODT.
If you wish insert a field to replace (text-input is used), double click on the treeview node or click on Insert Field button :
If you wish to generate table from a Java List, you must mark the field name as "list" with FieldsMetadata (see here for more information. Here developers.Mail is marked as list, so you can insert directly the developers.Mail in a table cell like a simple field that we have done below (Insert Field section).
You can manage loop for fields anywhere (see here for more information). To do that, select fields marked as list and click on "Insert List" button :
the List Dialog opens and you can change the item name list if you want. The dialog preview the 3 text-input which will be added (start loop + body loop+end loop) :
If you click on OK button, 3 text-input will be added (start loop + body loop+end loop) :
When you are designing your ODT, it's possible to preview the result of the generated ODT. To do that, click on Preview button to open the preview generated ODT:
As you can notice, text-input are replaced with some values. Those values comes from a JSON file. If you go at to the folder which contains the project.fields.xml, you will see that there is project.fields.xml-data which appears :
This folder contains the data of the project.fields.xml (each xxx.fields.xml are a data folder which is named with xxx.fields.xml-data). If you go to the project.fields.xml-data folder you will see the *default.json" file which was generated by the fr.opensagres.xdocreport.document.tools.Main class by using the XML fields file project.fields.xml :
This JSON files emulates your data coming from Java Model. If you edit the project.fields.xml-data/default.json you will see the JSON data which is used by the macro for the preview :
{
"project": {"Name": "Name_Value"},
"developers": [
{
"Name": "Name_Value0",
"Mail": "Mail_Value0",
"LastName": "LastName_Value0"
},
{
"Name": "Name_Value1",
"Mail": "Mail_Value1",
"LastName": "LastName_Value1"
},
{
"Name": "Name_Value2",
"Mail": "Mail_Value2",
"LastName": "LastName_Value2"
},
{
"Name": "Name_Value3",
"Mail": "Mail_Value3",
"LastName": "LastName_Value3"
},
{
"Name": "Name_Value4",
"Mail": "Mail_Value4",
"LastName": "LastName_Value4"
},
{
"Name": "Name_Value5",
"Mail": "Mail_Value5",
"LastName": "LastName_Value5"
},
{
"Name": "Name_Value6",
"Mail": "Mail_Value6",
"LastName": "LastName_Value6"
},
{
"Name": "Name_Value7",
"Mail": "Mail_Value7",
"LastName": "LastName_Value7"
},
{
"Name": "Name_Value8",
"Mail": "Mail_Value8",
"LastName": "LastName_Value8"
},
{
"Name": "Name_Value9",
"Mail": "Mail_Value9",
"LastName": "LastName_Value9"
}
]
}You can modify the default.json with your values like this :
{
"project": {"Name": "XDocReport"},
"developers": [
{
"Name": "ZERR",
"Mail": "angelo.zerr@gmail.com",
"LastName": "Angelo"
},
{
"Name": "Leclercq",
"Mail": "pascal.leclercq@gmail.com",
"LastName": "Pascal"
}
]
}If you launch the preview, you will see the preview generated ODT like this:
When you design your report, you must pay attention to follow syntax of the template engine to manage fields to replace, loop, condition, etc. For instance if you type just for Velocity engine the directive
#end
in the ODT, Velocity will throw an error, because there is not start if, foreach, etc.
The OOo extension fr.opensagres.xdocreport.openoffice.macro-xxx.oxt is enable to display in a dialog box the stack trace of the report process if there is error. To test it, type just
#end
in your ODT :
If you click on Preview menu, the popup dialog with error appears with stack trace thrown by Velocity :
[# Reporting with Java model
Now your ODT report is ready, and you can use it with XDocReport. Save your ODT with project.odt name into the xdocreport-quickstart-odt/src/fr/opensagres/xdocreport/quickstart folder.
Create the Java Main fr.opensagres.xdocreport.quickstart.GenerateODTReport like this :
package fr.opensagres.xdocreport.quickstart;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.ArrayList;
import java.util.List;
import fr.opensagres.xdocreport.core.XDocReportException;
import fr.opensagres.xdocreport.document.IXDocReport;
import fr.opensagres.xdocreport.document.registry.XDocReportRegistry;
import fr.opensagres.xdocreport.quickstart.model.Developer;
import fr.opensagres.xdocreport.quickstart.model.Project;
import fr.opensagres.xdocreport.template.IContext;
import fr.opensagres.xdocreport.template.TemplateEngineKind;
import fr.opensagres.xdocreport.template.formatter.FieldsMetadata;
public class GenerateODTReport {
public static void main(String[](http://wiki.xdocreport.googlecode.com/git/screenshots/ODTReportingQuickStart_ErrorPreview2.png)) args) throws IOException,
XDocReportException {
// 1) Load ODT file by filling Velocity template engine and cache
// it to the registry
InputStream in = GenerateODTReport.class
.getResourceAsStream("project.odt");
IXDocReport report = XDocReportRegistry.getRegistry().loadReport(in,
TemplateEngineKind.Velocity);
// 2) Create fields metadata to manage lazy loop (#forech velocity)
// for table row.
// 1) Create FieldsMetadata by setting Velocity as template engine
FieldsMetadata fieldsMetadata = report.createFieldsMetadata();
// 2) Load fields metadata from Java Class
fieldsMetadata.load("project", Project.class);
// Here load is called with true because model is a list of Developer.
fieldsMetadata.load("developers", Developer.class, true);
// 3) Create context Java model
IContext context = report.createContext();
Project project = new Project("XDocReport");
context.put("project", project);
// Register developers list
List<Developer> developers = new ArrayList<Developer>();
developers
.add(new Developer("ZERR", "Angelo", "angelo.zerr@gmail.com"));
developers.add(new Developer("Leclercq", "Pascal",
"pascal.leclercq@gmail.com"));
context.put("developers", developers);
// 4) Generate report by merging Java model with the ODT
OutputStream out = new FileOutputStream(new File("project_out.odt"));
report.process(context, out);
}
}If you run this Java Main, it will generate you the ODT project_out.odt in the xdocreport-quickstart-odt folder: