Master Word Document Generation in Spring Boot 3 with poi‑tl: A Step‑by‑Step Guide

Introduction

Generating Word documents is a common requirement for contracts, reports, and data summaries. Using a template engine such as POI‑TL together with dynamic data can automate this process, ensuring consistent formatting while allowing personalization.

What is POI‑TL?

POI‑TL is a Word template engine that renders new documents from a Word template and a data model. It preserves the rich styles of the template and supports tags for text, images, tables, loops, and conditional sections.

Environment

Spring Boot 3.4.2

1. Preparation

1.1 Add Maven Dependency

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

1.2 Prepare Word Template

The template (e.g., person_template.docx) contains placeholders for fields, images, tables, lists, sections, and charts.

1.3 Define Data Model

public class PersonalInfo {
  private String college;
  private String major;
  private String name;
  private String gender;
  private String nation;
  private String birthDate;
  private String nativePlace;
  private String currentLocation;
  private String education;
  private String politicalStatus;
  private String maritalStatus;
  private String employmentIntention;
  private String hobbies;
  private String selfEvaluation;
  private String address;
  private String phoneNumber;
  private String email;
  private String img;
}

2. Practical Cases

2.1 Generate Document from Template

PersonalInfo person = new PersonalInfo(
    "计算机学院",
    "软件工程",
    "张三",
    "男",
    "汉族",
    "1995年08月",
    "湖南长沙",
    "北京",
    "本科",
    "共青团员",
    "未婚",
    "希望从事软件开发相关工作",
    "编程、阅读、篮球",
    "本人学习能力强，有良好的团队合作精神和沟通能力",
    "北京市海淀区XX街道XX号",
    "13812345678",
    "[email protected]",
    "https://img1.baidu.com/it/u=2709364071,2311129161&fm=253&app=138&f=JPEG?w=800&h=800"
);
ClassPathResource resource = new ClassPathResource("templates/person_template.docx");
XWPFTemplate.compile(resource.getInputStream())
    .render(person)
    .writeToFile("e:/person.docx");

2.2 Generate Table Data

Map<String, Object> dataModal = new HashMap<>();
dataModal.put("hobbies", Tables.of(new String[][]{{"烹饪","绘画","电影","徒步","编程"}}).border(BorderStyle.DEFAULT).create());
XWPFTemplate.compile(resource.getInputStream())
    .render(dataModal)
    .writeToFile("e:/person.docx");

2.3 Generate List

List tags start with * (e.g., {{*list}}) and render bullet or numbered lists.

2.4 Use Sections (Blocks)

Sections are defined with {{?section}} and {{/section}}. If the block value is null, false, or an empty collection, the content is omitted; otherwise it repeats for each element.

2.5 Generate Charts

ChartMultiSeriesRenderData chart = Charts.ofMultiSeries(
    "ChartTitle",
    new String[]{"中文","English"})
    .addSeries("地区", new Double[]{15.0, 6.0})
    .addSeries("语言", new Double[]{223.0, 119.0})
    .create();
dataModal.put("barChart", chart);
XWPFTemplate.compile(resource.getInputStream())
    .render(dataModal)
    .writeToFile("e:/person.docx");

2.6 Enable Spring Expression Language (SpEL)

ConfigureBuilder builder = Configure.builder();
builder.useSpringEL();
XWPFTemplate.compile(resource.getInputStream(), builder.build())
    .render(dataModal)
    .writeToFile("e:/person.docx");

2.7 Provide Download Endpoint

@GetMapping("/download")
public void download() throws Exception {
    // prepare data model as shown above
    response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE);
    response.setCharacterEncoding("utf-8");
    String fileName = URLEncoder.encode("个人简历.docx", "UTF-8").replaceAll("\\+", "%20");
    response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=utf-8''" + fileName);
    XWPFTemplate.compile(resource.getInputStream())
        .render(dataModal)
        .write(response.getOutputStream());
    response.flushBuffer();
}

The above steps cover the complete workflow of creating a Word document with POI‑TL in a Spring Boot 3 application, from dependency setup to template design, data binding, advanced features like tables, lists, sections, charts, SpEL, and finally exposing the document for download.