Skip to main content

Template Options

Configuring template rendering behavior with OfficeTemplateOptions.

Parallel Processing​

Enable parallel execution for {for} loops and $map operations:

val options = OfficeTemplateOptions()
    .parallel(true)

val template = OfficeTemplate.fromFile("Template.docx", options)

Performance Benefits​

Parallel mode can significantly speed up rendering when you encounter performance bottlenecks while evaluating template expressions.

This might happen for large audit reports that pull in data from a dozen data sources.

Thread Safety Requirement​

When using parallel mode, all objects in your data map must be thread-safe:

  • Immutable objects: Safe by default (data classes, records, strings, numbers)
  • Read-only access: Safe if you only read properties
  • Mutable shared state: Must use synchronization or thread-safe collections
// Safe: immutable data class
data class Product(val name: String, val price: Double)

// Safe: read-only list
val products: List<Product> = listOf(...)

// Unsafe: mutable list being modified during iteration
val results = mutableListOf<String>()  // Don't share this in parallel mode

If your data objects have side effects or mutable state, keep parallel mode disabled (the default).

Custom Delimiters​

By default, DocStencil uses { and } as delimiters for template expressions. If your documents already contain curly braces for other purposes, you can customize the delimiters:

val options = OfficeTemplateOptions(
    delimiters = OfficeTemplateOptions.Delimiters("<<", ">>")
)

val template = OfficeTemplate.fromFile("Template.docx", options)

With custom delimiters, your template would use <<name>> instead of {name}.

Locale​

The locale option controls how builtin formatting functions behave. This affects date formatting, number formatting, and other locale-sensitive operations:

val options = OfficeTemplateOptions(
    locale = Locale.GERMANY
)

val template = OfficeTemplate.fromFile("Template.docx", options)

By default, DocStencil uses Locale.getDefault() from the JVM.

Strip Invalid XML Characters​

Office documents use XML internally. If your data contains characters that are invalid in XML (such as certain control characters), rendering will fail. Enable stripInvalidXmlChars to automatically remove these characters:

val options = OfficeTemplateOptions(
    stripInvalidXmlChars = true
)

val template = OfficeTemplate.fromFile("Template.docx", options)

This is useful when processing data from external sources that may contain unexpected characters. The default is false.

Exception Stack Traces​

By default, DocStencil prints stack traces when exceptions occur during parsing or rendering. You can disable this for cleaner error output in production:

val options = OfficeTemplateOptions(
    printExceptionStackTraces = false
)

val template = OfficeTemplate.fromFile("Template.docx", options)

When disabled, exceptions are still thrown but without printing the full stack trace to stderr. The default is true.