Generate Word Docs with POI‑TL: A Minimal‑Code Template Engine for Java

When working on large projects, developers often spend a lot of time writing repetitive documentation. POI‑TL (POI‑template‑language) is a Word‑specific template engine based on Apache POI that can generate Word files directly from user‑provided data, dramatically reducing manual effort.

Apache POI is a free, open‑source Java API for reading and writing Office formats. POI‑TL leverages POI to allow you to place any content anywhere in a Word document using simple placeholders.

For example, to create a document named TJ君真棒.docx containing the text {{title}}, you only need one line of code:

// Core API – one‑line generation
XWPFTemplate.compile("TJ君真棒.docx")
    .render(new HashMap<String, Object>() {{
        put("title", "Poi‑tl Template Engine");
    }})
    .writeToFile("out_TJ君真棒.docx");

The engine follows a Template + Data‑Model = Output design. The Configure class provides extensive configuration, such as custom syntax, plugin registration, and error‑handling strategies.

public class Configure {
    private static final String DEFAULT_GRAMER_REGEX = "[\\w\\u4e00-\\u9fa5]+(\\.[\\w\\u4e00-\\u9fa5]+)*";
    private Map<String, RenderPolicy> customPolicys = new HashMap<>();
    private Map<Character, RenderPolicy> defaultPolicys = new HashMap<>();
    private String gramerPrefix = "{{";
    private String gramerSuffix = "}}";
    // ... other configuration fields and builder methods ...
}

The TemplateVisitor parses the Word document, traverses paragraphs, tables, headers, and footers, and creates ElementTemplate objects for each placeholder, delegating rendering to the appropriate RenderPolicy.

public class TemplateVisitor implements Visitor {
    private Configure config;
    private List<ElementTemplate> eleTemplates;
    // visitDocument, visitParagraphs, visitTables, etc.
}

Render policies are extension points that define how each tag is rendered. POI‑TL also offers a rich set of built‑in policies for text, images, tables, numbers, and custom DOCX templates.

By studying the provided examples and configuration options, developers can quickly master POI‑TL and automate the generation of complex Word documents, freeing more time for actual code development.