Word processor compatible templating system

This software allows clients to use office suite documents for templating automated document generation.

Template Syntax

Template files may contain the following expressions.

Value substitution

Used to display value from the template data object.

Examples:

Show value under a given key: {%=key_name%}
Show value under a given key in a map under a given key: {%=outer_key.inner_key %}

Conditional blocks

Put a value between conditional blocks to toggle its visibility depending on a value in the data object.

Examples:

if-then branching: {%if condition %}THEN part comes here {%end%}
if-then-else branching: {%if condition %}THEN part comes here {%else%} else part comes here{%end%}

Repeating blocks

Repeat a block for each item in a list in the data object.

For example if xs is a list then the following repeats the BODY part for every item: {%for x in xs%} BODY {%end%}

The BODY part has a new binding on every iteration so you can access every element in a collection via the x iterator variable.

Function calls and arithmetic

You can call custom functions in expressions. For example: {%=coalesce(x.price, x.cost, "N/A")%}

You can also call many arithmetic operators. For example: {%= x*x+x+2%}

Concepts

The following is a description of the basic concepts of this library.

Process

A {@link stencil.Process} instance helps you manage the lifecycle of the converters and the whole document processing process. Use the {@link stencil.ProcessFactory} to receive Process instances.

PreparedTemplate

A raw template document file needs to be preprocessed if we want to use it in our template engine. The preprocessing step simplifies the document and prepares the control sequences in it to make it simpler and faster to render the final document.

Preparing a template file should take an order of a few dozen milliseconds. It may not always be necessary to store the prepared template object. Sometimes it is perfectly fine to prepare the template files on the fly when needed.

Custom Functions

See: {@link stencil.functions} package.

Example code

This example takes a DOCX from the file system, feeds it some template data and produces a PDF file.


      // load template data
      TemplateData data = TemplateData.fromMap(...);

      // create a new process object with a local libreoffice installation
      Process process = ProcessFactory.fromLibreOfficeHome("/home/bin/libreoffice");
      // optionalyy, register custom functions here: process.registerFunctions(fun1, fun2, fun3, ...);

      // we start the service
      process.start();

      // call rendering process all in one.
      process.render(new File("template_file.docx"), data, new File("output_file.pdf"));

      // we stop the service.
      process.stop();