Open Source Java Library for DOCX Template Processing

Getting Started with docx-stamper

docx-stamper is available via Maven from JCenter. Add the repository and dependency to your pom.xml. You must also include a compatible version of docx4j yourself (e.g., docx4j-JAXB-ReferenceImpl). For the latest version and source code, visit the [docx-stamper GitHub](https://github.com/thombergs/docx-stamper) repository. The library is lightweight and integrates easily into existing Java projects.

<repositories>
  <repository>
    <id>jcenter</id>
    <url>https://jcenter.bintray.com/</url>
  </repository>
</repositories>

<dependency>
  <groupId>org.wickedsource.docx-stamper</groupId>
  <artifactId>docx-stamper</artifactId>
  <version>1.5.0</version>
</dependency>

Replace Expressions in DOCX Templates

docx-stamper enables dynamic content injection by replacing expressions like `${person.name}` in the template text using Spring SpEL. It supports strings, objects, dates, and images, preserving original formatting. You can customize date formatting or add custom resolvers for additional types. If an expression fails to resolve, it remains unchanged unless configured otherwise. This makes it ideal for generating personalized documents with minimal code.

MyContext context = new MyContext();
context.setPerson(new Person("Alice"));
InputStream template = new FileInputStream("template.docx");
OutputStream out = new FileOutputStream("output.docx");
DocxStamper stamper = new DocxStamperConfiguration().build();
stamper.stamp(template, context, out);
out.close();

Conditional Display & Repetition via Comments

docx-stamper supports advanced template control using comments in the .docx file. You can conditionally show/hide paragraphs, repeat table rows or document parts, and replace words dynamically using expressions like `displayParagraphIf(boolean)` or `repeatTableRow(List)`. This allows building complex layouts such as invoices with variable line items or reports with conditional sections—all without modifying the Java code.

List orders = Arrays.asList(
  new Order("Item A", 2),
  new Order("Item B", 5)
);
context.setOrders(orders);
// In template: comment on table row: repeatTableRow(${orders})
stamper.stamp(template, context, out);

Custom Type Resolvers & Functions

docx-stamper allows extending supported expression types via custom `ITypeResolver` implementations. You can also register custom functions for SpEL, such as formatting numbers or dates differently. This flexibility lets you handle domain-specific logic directly in templates—like `${toUppercase(customer.name)}`—without cluttering your Java code, enabling cleaner and more expressive templates.

DocxStamper stamper = new DocxStamperConfiguration()
  .exposeInterfaceToExpressionLanguage(
    UppercaseFunction.class, 
    new UppercaseFunctionImpl()
  ).build();

public interface UppercaseFunction {
  String toUppercase(String s);
}
public static class UppercaseFunctionImpl implements UppercaseFunction {
  public String toUppercase(String s) { return s.toUpperCase(); }
}

Error Handling & Evaluation Context Customization

docx-stamper provides robust error handling: by default, unresolved expressions throw exceptions, but you can disable this with `setFailOnUnresolvedExpression(false)`. You can also fully customize the SpEL evaluation context via `EvaluationContextConfigurer`, enabling custom variable resolution, security settings, or performance tuning. This ensures safe and predictable behavior in production environments.

DocxStamper stamper = new DocxStamperConfiguration()
  .setFailOnUnresolvedExpression(false)
  .build();
// Now unresolved expressions are silently skipped