Getting Started with Office-stamper

This guide helps you get started with Office-stamper, from adding the dependency to your project to creating your first document.

Adding Office-stamper to Your Project

Maven

Add the following dependency to your pom.xml:

<dependency>
    <groupId>pro.verron.office-stamper</groupId>
    <artifactId>engine</artifactId>
    <version>3.1</version>
</dependency>

You also need to provide a dependency to Docx4J:

<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-core</artifactId>
    <version>11.5.8</version>
</dependency>
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-JAXB-ReferenceImpl</artifactId>
    <version>11.5.8</version>
</dependency>

Gradle

Add the following to your build.gradle:

dependencies {
    implementation 'pro.verron.office-stamper:engine:3.1'
    implementation 'org.docx4j:docx4j-core:11.5.8'
    implementation 'org.docx4j:docx4j-JAXB-ReferenceImpl:11.5.8'
}

Basic Usage

Here’s an example of how to use Office-stamper:

void main() {
    // a java Bean, a record, or a map to use as context for the expressions found in the template.
    var context = Map.of(
            "company", Map.of("name", "Duff"),
            "customer", Map.of("name", "Homer"),
            "order", Map.of("id", "123", "date", "2023-01-01")
    );

    // an instance of the stamper
    var stamper = OfficeStampers.docxStamper();

    try(
        // Path to the .docx template file
        var template = Files.newInputStream(Paths.get("your/docx/template/file.docx"));
        // Path to write the resulting .docx document
        var output = Files.newOutputStream(Paths.get("your/desired/output/path.docx"))
    ) {
        stamper.stamp(template, context, output);
    }
}

Creating a Template

  1. Open Microsoft Word or any other word processor that can save in .docx format.
  2. Create your document with placeholders for dynamic content
  3. Use expressions like ${person.name} for natural replacements.
  4. Add comments with special instructions for more advanced features
  5. Save the document as a .docx file

Example Template

Here’s what a plain template might look like:

Dear ${customer.name},

Thank you for your order #${order.id} placed on ${order.date}.

Your order details:
${order.description}

Total amount: $${order.amount}

Sincerely,
${company.name}

Next Steps