verron.pro logo verron.pro

Template Expressions

The foundation of Office-stamper lies in its ability to replace expressions within the text of a .docx template document.

Basic Expression Syntax

Office-stamper uses the Spring Expression Language (SpEL) for its template expressions. Expressions are enclosed in ${…​} delimiters.

Examples:

${person.name}
${order.total * 0.2}
${person.age > 18 ? 'Adult' : 'Minor'}

Expression Evaluation

When Office-stamper processes a template, it evaluates each expression based on context. The result of the evaluation replaces the expression in the output document.

Context Object

The context object is a Java object that contains the data you want to insert into your document. It can be:

  • A POJO (Plain Old Java Object) with getters
  • A Map with string keys
  • Any object that can be accessed using SpEL

Formatting Preservation

Office-stamper maintains the original text’s formatting in the template. This means that if your expression is bold, italic, or has any other formatting, the replacement text should receive the same formatting.

Spring Expression Language Features

Office-stamper gives you full access to the extensive feature set of Spring Expression Language (SpEL).

Some useful SpEL features include:

  • Property access: ${person.address.city}
  • Method invocation: ${person.getFullName()}
  • Array/List access: ${orders[0].id}
  • Map access: ${data['key']}
  • Operators: ${price * quantity}
  • Conditionals: ${person.age > 18 ? 'Adult' : 'Minor'}
  • Regular expressions: ${name matches '[A-Z][a-z]+'}
  • Collection projection: ${orders.![total]}
  • Collection selection: ${orders.?[total > 100]}

Resolvers

Office-stamper uses a chain of resolvers to convert the result of an expression evaluation into a string, and insert it into the document. Resolvers apply in a certain order.

Default Resolvers When the placeholder resolves to a The replacement is
Resolvers.image() pro.verron.officestamper.preset.Image an inline image
Resolvers.legacyDate() java.util.Date A formatted Date string (default "dd.MM.yyyy")
Resolvers.isoDate() java.time.LocalDate A formatted Date string (default DateTimeFormatter.ISO_LOCAL_DATE)
Resolvers.isoTime() java.time.LocalTime A formatted Date string (default DateTimeFormatter.ISO_LOCAL_TIME)
Resolvers.isoDateTime() java.time.LocalDateTime A formatted Date string (default DateTimeFormatter.ISO_LOCAL_DATE_TIME)
Resolvers.nullToEmpty() null An empty string
Resolvers.fallback() Object The result of the call to String.valueOf() method on the object

If a placeholder fails to resolve successfully, Office-stamper skip it, and the placeholder in the document remains the same as its initial state in the template.

Custom Resolvers

You can create your own resolvers to handle specific types or formatting requirements. See the Custom Settings section for more information.

Error Handling

By default, if an expression cannot be evaluated (due to syntax errors, missing properties, and so on), Office-stamper throws an exception. You can customize this behavior using exception resolvers. See the Troubleshooting section for more details.

Next Steps