Using Poi-tl to Export Word Documents with Templates in Java

Background

Based on business requirements, we need to assemble test questions into an exam paper and export it as a .docx Word document, supporting proper display and editing of formula data.

Solution Selection

Various ways to export Word were considered; after evaluation we chose the Poi‑tl approach because it uses .docx templates directly, is Java‑based, and offers a comprehensive API.

Template configuration is convenient; you can use a .docx file as the template and create it with simple syntax.

Since it is Java, using Java code is more convenient.

The API is relatively complete and can satisfy most current requirements.

Freemarker was rejected because image placement requires knowing the position after filling content, making it cumbersome.

Comparison of Word export solutions

Solution

Portability

Functionality

Ease of Use

Poi-tl

Java cross‑platform

Word template engine

Based on Apache POI

Apache POI

Java cross‑platform

Rich Apache project

Documentation incomplete

Freemarker

XML cross‑platform

Text only, limited

Not recommended, XML maintenance heavy

OpenOffice

Requires OpenOffice deployment, low portability

-

Needs OpenOffice API knowledge

HTML browser export

Depends on browser, low portability

HTML poorly matches Word format

-

Jacob, winlib

Windows platform

-

Complex, not recommended

Implementation Details

Poi‑tl Overview

Poi‑tl is a Word template engine that generates new documents from a template and data.

Poi‑tl API

All tags start with {{ and end with }} . The following sections describe how to fill different data types.

Text tags

{{name}}
{{author}}
{{link}}
{{anchor}}

Data format for text

Map
data = new HashMap<>();
data.put("name", "Sayi");
data.put("author", new TextRenderData("000000", "Sayi"));
data.put("link", new HyperlinkTextRenderData("website", "http://deepoove.com"));
data.put("anchor", new HyperlinkTextRenderData("anchortxt", "anchor:appendix1"));

Image tags (start with @, size required)

{{@localImg}}
{{@streamImg}}
{{@urlImg}}
{{@bufferImg}}

Data format for images

Map
data = new HashMap<>();
// local image
data.put("localImg", Pictures.ofLocal("sayi.png").size(120, 120).create());

// image stream
data.put("streamImg", Pictures.ofStream(new FileInputStream("logo.jpeg"), PictureType.JPEG)
  .size(100, 120).create());

// network image (consider latency)
data.put("urlImg", Pictures.ofUrl("http://deepoove.com/images/icecream.png", PictureType.PNG)
  .size(100, 100).create());

// java BufferedImage
data.put("bufferImg", Pictures.ofBufferedImage(bufferImage, PictureType.PNG)
  .size(100, 100).create());

Table tags (start with #)

{{#table}}

Data format for tables

// a 2×2 table
Map
data = new HashMap<>();
data.put("table", Tables.of(new String[][] {
    new String[] { "00", "01" },
    new String[] { "10", "11" }
}).border(BorderStyle.DEFAULT).create());

Block pairs

{{?person}}
  Hi {{name}}!
  {{?models}}
    {{modelName}}
  {{/models}}
{{/person}}

Block pairs allow flexible handling of nullable data, support iteration and nesting.

Getting Started

Add Maven dependency:

<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>poi-tl</artifactId>
  <version>1.9.1</version>
</dependency>

Create a Word template (template.docx) containing tags such as {{title}}.

Implement export code:

XWPFTemplate template = XWPFTemplate.compile("template.docx").render(
  new HashMap
() {{
    put("title", "Hi, poi-tl Word template engine");
  }});
template.writeAndClose(new FileOutputStream("output.docx"));

Conclusion

Using Poi‑tl for Word export is convenient and fast; this article covered basic usage, but Poi‑tl offers many more plugins and extensibility. Future articles will discuss formula rendering in Word documents.

References:

Poi‑tl API: http://deepoove.com/poi-tl