poi-tl Documentation

Sections are defined by a start tag {{?name}} and an end tag {{/name}}. They behave differently based on the data type:

1. False/Empty: If the value is null, false, or an empty collection, the content inside the section is hidden.
2. Non-False/Non-Collection: If the value is a single object (not a collection), the content is rendered once.
3. Non-Empty Collection: If the value is a collection, the content is looped $N$ times (foreach). Use {{=#this}} inside the loop to refer to the current object.

Add the following dependency to your pom.xml to use poi-tl. Note that version 1.12.x requires Apache POI version 5.2.2 or higher.

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

To generate a document from a template, use the XWPFTemplate.compile() method to load your .docx template, render() it with a data model (e.g., a HashMap), and then writeToFile() to save the output.

//The core API uses a minimalist design, only one line of code is required
XWPFTemplate.compile("template.docx").render(new HashMap<String, Object>(){{
         put("title", "poi-tl template engine");
}}).writeToFile("out_template.docx");

The poi-tl-cli allows you to generate Word documents from templates using a JSON data model via the command line. You can provide the data model either as a raw JSON string or as a path to a .json file.

Basic Usage:

java -jar poi-tl-cli.jar -t <template_path> -d <data_model_path_or_json> -o <output_path>

Nesting allows you to merge one Word template into another using the + prefix, such as {{+nested}}. This is useful for including sub-templates. Use Includes.ofLocal("path.docx").setRenderModel(data).create() to prepare the nested template with its own data model.

class AddrModel {
  String addr;
  public AddrModel(String addr) {
    this.addr = addr;
  }
}

List<AddrModel> subData = new ArrayList<>();
subData.add(new AddrModel("Hangzhou,China"));
subData.add(new AddrModel("Shanghai,China"));
put("nested", Includes.ofLocal("sub.docx").setRenderModel(subData).create());

Picture tags start with @. For example, {{@logo}} will replace the tag with an image. The data model value can be a URL string, a local file path, or a structure created via Pictures (e.g., Pictures.ofLocal(...).size(...).create()).

put("watermelon", "assets/watermelon.png");
put("watermelon", "http://x/lemon.png");
put("lemon", Pictures.ofLocal("sob.jpeg", PictureType.JPEG).size(24, 24).create());

Table tags start with #. A tag like {{#table}} will be rendered as a Word table with rows and columns determined by the data provided in the model. Use Tables.of(data).create() to prepare the table data.

put("table", Tables.of(new String[][] {
                new String[] { "Song name", "Artist" }
            }).border(BorderStyle.DEFAULT).create());

List tags start with *. A tag like {{*list}} renders as a Word symbol list or numbered list. Use Numberings.create(strings...) to provide the list content.

put("list", Numberings.create("Plug-in grammar",
                  "Supports word text, pictures, table...",
                  "Template, not just template, but also style template"));

When providing a JSON data model to the CLI, the following specialized render types are supported via the type field in your JSON:

• markdown: Renders Markdown content using MarkdownRenderData.
• code: Renders highlighted code blocks using HighlightRenderData.
• markdown-file: Renders Markdown content from a file using FileMarkdownRenderData.

Additionally, the CLI includes built-in support for:

• toc: Table of Contents via TOCRenderPolicy.
• :: Comments via CommentRenderPolicy.
• ;: Attachments via AttachmentRenderPolicy.
• ~: Code highlighting via HighlightRenderPolicy.
• -: Markdown via MarkdownRenderPolicy.

The following flags are available for the poi-tl-cli tool: