XDocReport Library

This module [isis-module-xdocreport] provides a wrapper around XDocReport. XDocReport is an API to merge XML documents into MS Office (.docx) or OpenOffice (.odt) files, optionally converting into another format, notably PDF.

How to configure/use

Classpath

Update your classpath by adding this dependency in your dom project’s pom.xml:

<dependency>
    <groupId>org.isisaddons.module.xdocreport</groupId>
    <artifactId>isis-module-xdocreport-dom</artifactId>
    <version>1.15.1.1</version>
</dependency>

Check for later releases by searching Maven Central Repo.

For instructions on how to use the latest -SNAPSHOT, see the contributors guide.

Bootstrapping

In the AppManifest, update its getModules() method, eg:

@Override
public List<Class<?>> getModules() {
    return Arrays.asList(
            ...
            org.isisaddons.module.xdocreport.dom.XDocReportModule.class,
            ...
    );
}

API

This module provides a single service, called XdocReportService. It has the following API:

@DomainService(nature = NatureOfService.DOMAIN)
public class XDocReportService {
    public byte[] render(
            byte[] templateBytes,                       (1)
            XDocReportModel dataModel,                  (2)
            OutputType outputType)                      (3)
        throws IOException { ... }
}
1 the input template, eg the bytes of a Word .docx file
2 holds the data to be merged into the template, discussed further below

The XDocReportModel parameter holds the data to be merged into the template. It is basically just a map of (Data) objects, where each such is either a single object, or is a list of objects:

public interface XDocReportModel {

    @lombok.Data
    class Data {
        private final Object obj;
        private final Class<?> cls;
        private final boolean list;

        public static <T> Data list(final List<T> objects, final Class<T> cls) {
            return new Data(objects, cls, true);
        }

        public static <T> Data object(final T object) {
            return new Data(object, object.getClass(), false);
        }
    }

    Map<String, Data> getContextData();
}

The OutputType meanwhile is simply an enum defining:

public enum OutputType {
    DOCX,
    PDF
}

Example Usage

From the unit tests:

// given
InputStream in= new FileInputStream(new File("src/test/java/org/isisaddons/module/xdocreport/dom/example/template/Project-template.docx"));
final byte[] templateBytes = IOUtils.toByteArray(in);

Project project = new Project("XDocReport");
List<Developer> developers = new ArrayList<>();
developers.add(new Developer("ZERR", "Angelo", "angelo.zerr@gmail.com"));
developers.add(new Developer("Leclercq", "Pascal", "pascal.leclercq@gmail.com"));
final ProjectDevelopersModel dataModel = new ProjectDevelopersModel(project, developers);   (1)

// when
final byte[] docxBytes = service.render(templateBytes, dataModel, OutputType.DOCX);

// then
IOUtils.write(docxBytes,new FileOutputStream(new File("target/Project.docx")));
1 see below

and

@Data
public class ProjectDevelopersModel implements XDocReportModel {

    private final Project project;
    private final List<Developer> developers;

    @Override
    public Map<String, Data> getContextData() {
        return ImmutableMap.of(
                "project", Data.object(project),
                "developers", Data.list(developers, Developer.class));
    }
}

Known issues

None known at this time.

Dependencies

Maven can report modules dependencies using:

mvn dependency:list -o -pl modules/lib/xdocreport/impl -D excludeTransitive=true

which, excluding Apache Isis itself, returns these compile/runtime dependencies:

org.javassist:javassist:jar:3.19.0-GA
fr.opensagres.xdocreport:fr.opensagres.xdocreport.template.freemarker:jar:1.0.6
fr.opensagres.xdocreport:fr.opensagres.xdocreport.converter.docx.xwpf:jar:1.0.6
fr.opensagres.xdocreport:fr.opensagres.xdocreport.document.docx:jar:1.0.6

For further details on 3rd-party dependencies, see: