Open-source project
Sayi/poi-tl avatar
Sayi/poi-tl

poi-tl: the tag grammar, the logic-less design, and the modules around it

Generate awesome word(docx) with template

5,176 stars1,132 forksJavaApache-2.0

At a glance

What is it?
poi-tl fills a Word docx from a template and a Map, with no control flow inside the document. Here is the tag grammar, the built-in renderers, and the gaps behind the advertised feature list.
Who is it for?
poi-tl fits one shape of work: a designer builds the document in Word, Java fills in the values, and nobody needs logic inside the template. That is a real strength, and it explains why the tag set is small.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 33 days ago.
What is it written in?
Mainly Java, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Sayi/poi-tl5,176 ★ · +27
Star history
Repository2026-09-232026-11-15
Sayi/poi-tl5.1k5.2k

27 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The runtime is compile, render, writeToFile

poi-tl produces a new Word file out of a Word file: you hand it a .docx template and a data model, and it hands back a rendered document. The runtime is three calls, XWPFTemplate.compile, render, writeToFile, and the artifact drops into a Maven build like any other library:

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

The note attached to that snippet is worth reading twice: poi-tl 1.12.x requires JDK 1.8+ and Apache POI 5.2.2+.

java
// Core API: one-liner compilation and rendering
XWPFTemplate template = XWPFTemplate.compile("template.docx")
    .render(Collections.singletonMap("title", "Hi, poi-tl Word Template Engine"));

template.writeToFile("output.docx");

Open output.docx afterwards and the value of the title key is there. Before any of that runs, create template.docx and type {{title}} into a paragraph, because the setup on show needs no configuration file and no template registry. The path string inside compile is the whole configuration.

Two curly braces, one name, one prefix character

The whole language is small on purpose. A tag is two curly braces around a name, and one character identifies what the tag does: {{title}} is a tag, {{?title}} is also a tag, title is the key it reads from the data model, and ? marks the kind. Everything else in the engine is built on that grammar.

poi-tl calls itself a logic-less template engine: no control structures, no variable assignment, only tags. The design notes it quotes argue that powerful constructs such as variable assignment and conditional statements make it easy to change the look of an application from inside its templates, at the cost of turning the templates themselves into part of the application logic. poi-tl takes the other side of that trade, and the bill moves to whoever fills the model. The feature table does list SpringEL expression support, though, and the loop variables table shows `{{_index + 1}}` inside a template. Branching exists as a tag instead of a statement, listed as If Condition for showing or hiding text, paragraphs, pictures, tables, lists and charts, and as Foreach Loop for repeating that same range of content. Anything richer is a plug-in, which the project presents as a function callable from anywhere in the template.

A missing key clears the tag by default

The text tag is the simplest renderer. {{name}} takes a `String` or `TextRenderData` from the data model, and the fluent builder `Texts.of("Hello").color("000000").bold().create()` sets style from code. The README also says poi-tl preserves the fonts, colors, layouts and alignments of the template in the generated document.

Picture and table tags take their shape from the data

Two tags decide their footprint at render time instead of at design time. A picture tag starts with @, so {{@logo}} looks up the key logo and swaps the tag for the image. The README pairs it with `PictureRenderData` and a fluent builder:

java
Pictures.ofLocal("logo.png").size(100, 100).create()

The Pictures builder sets the size, through size(100, 100) above. A table tag starts with #, {{#table}} renders as a Word table with N rows and N columns, and N is a property of the array you hand in:

java
Tables.of(new String[][]{{"A", "B"}, {"C", "D"}}).create()

Two consequences follow for the reader. A tag does not occupy a fixed place in the document, so one extra row can push a table onto a second page and one oversized picture can overflow a column a designer measured in Word.

The feature table is longer than the text behind it

The feature table claims a wide surface. It lists text, picture, table, numbering, and chart rendering with 3D bar, 3D column, 3D area, 3D line, radar and pie charts. It lists loop table row, loop table column, and ordered list loops that handle multiple levels. It lists Word attachment, Word Comments with create and modify, Word SDT structured document tags, tags inside text boxes, replacement of an original picture, bookmarks, anchors and hyperlinks, Markdown conversion, and code highlighting for 26 languages. Then expression language, described as full SpringEL support with OGNL and MVEL named as extension points; styles that code can set as well as the template; nested templates, sub-templates inside sub-templates; merge, including merging into a specified position; and plug-ins runnable anywhere in the document.

Treat that as a claim of surface rather than an API reference. The feature table does not say which of these arrived in which release; tag syntax is covered in a separate Tag Syntax & Built-in Renderers table, and the project homepage is deepoove.com/poi-tl/.

Six modules ship here, one coordinate is documented

The repository top level holds poi-tl/, plugin/ and support/ directories with a pom.xml, and the Maven snippet names exactly one artifact. Alongside them sit .editorconfig, a .travis.yml build file, a .github/ directory, .gitignore, LICENSE and README.md. The dependency block names com.deepoove:poi-tl at version 1.12.2 and nothing else, so no coordinates appear for anything under plugin/ or support/.

Read those two lists against each other. Markdown conversion and code highlighting are both advertised, and a plugin/ directory sits in the tree, but the Quick Start does not show how to switch either on: a second dependency, a config class, a jar you shade in. Adding Markdown to a document is not the one line change the feature row implies.

The version history is easy to read. Releases go v1.12.0 on 2022-04-14, v1.12.1 on 2022-12-29, and v1.12.2 on 2024-01-25. The default branch master was last pushed on 2026-10-13, the repository is not archived, and the license is Apache-2.0. Pin 1.12.2 rather than tracking the branch, because a newer commit can carry behaviour no release note mentions.

What this engine will not do, and who pays

Several gaps are worth pricing before adoption. The engine will not hold a layout still, since row counts, column counts and picture sizes all follow the data.

Two advertised features exist to close those gaps, and both move responsibility onto you. SpringEL sits in the data path, with OGNL and MVEL named as further extension points, so decide deliberately what reaches that path, in particular when values come from outside your own code. Plug-ins are the other lever: functions that run anywhere in the document, which is how a genuinely custom tag gets built, at the cost of shipping and versioning Java alongside the template.

Before the first production document: pin 1.12.2 with JDK 1.8+ and POI 5.2.2 or newer, render your longest expected data set rather than a two row sample, and open the result in Word to see what the tags left behind.

Editorial conclusion

poi-tl fits one shape of work: a designer builds the document in Word, Java fills in the values, and nobody needs logic inside the template. That is a real strength, and it explains why the tag set is small. It is a poor fit if you want rich logic inside the template, because poi-tl is logic-less by design, or a fixed page layout, because tables and pictures take their shape from the data. Before you trust it with a document a customer will read, pin version 1.12.2 with JDK 1.8+ and POI 5.2.2 or newer, render your longest data set, and read the full documentation on deepoove.com/poi-tl/.

Frequently asked questions

Which POI version does poi-tl 1.12.x require?

POI 5.2.2 or newer. The note attached to the Maven dependency in the README states that poi-tl 1.12.x requires POI version 5.2.2+. The same note requires JDK 1.8+.

What happens to a poi-tl tag whose key is missing from the data model?

The README does not state this in its Quick Start or tag syntax tables; the Quick Start only shows {{title}} being replaced with the value supplied for title.

Which poi-tl version does the Maven example install, and when was it released?

Version 1.12.2, released on 2024-01-25. The two earlier tags listed are v1.12.1 from 2022-12-29 and v1.12.0 from 2022-04-14, while the master branch itself was last pushed on 2026-10-13.

Can a poi-tl template loop over a list or repeat a table row?

Yes, but only through tags, since the engine has no control structures. The feature list names Foreach Loop, Loop table row, Loop table column and Loop ordered list, with support for multi-level ordered lists at the same time.

Does poi-tl generate markdown and syntax highlighted code?

Both are claimed in the feature table: conversion of Markdown to a Word document, and code highlighting for 26 languages with hundreds of colouring styles. The repository has a plugin/ directory, but the Quick Start gives no coordinates or setup steps for these features.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. Sayi/poi-tl on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sayi-poi-tl.svg)](https://hysenlabs.com/projects/sayi-poi-tl)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sayi-poi-tl.svg)](https://hysenlabs.com/projects/sayi-poi-tl)

Was this useful?