Templater is a reporting library which can be easily integrated into third party apps as advanced document generation engine. It works by binding provided data with specified template. Main goal is to provide customization options outside of development, so that reports/invoices/quotes and various other type of documents can be made to look as customers needs them.
Library has a minimal interface for providing data and various extension points for exposing specialized features not available in the library. This way same code is reused across all document generation, instead of having document being generated by writing special code just for that document.
These examples show various usages of the library.
Additional documentation is available from the official website.
Templater works by analyzing provided docx/xlsx/pptx/csv/xml document for tags.
Tags are snippets of text written in either [[tag]], {{tag}} or a <<tag>> format.
Tags can have metadata which can be used for various customization purposes, such as formatting, verbalization and others.
Tags placed in a resizable part of the document can be duplicated by Templater when paired with a collection input. Major difference from other templating solution is that repeating of a collection is implicit from tag definition instead of explicit by using for loop constructs. An example of this is a row in a table, list, page, sheet or the entire document.
Templater uses documents prepared in Microsoft Office (or some other editor), which allows for beautiful documents, without the need for writing code. This works great in most cases, although Templater must infer intention for the behavior from the structure of the document/tags.
Templater has minimal API for interaction:
- high level process method
- low level replace, resize and clone
and a builder API for customization.
Usage of Templater mostly consists from passing existing model to high level API.
Most data types are processed by Templater with conversion to string. In Excel some types are converted into native Excel formats, such as numbers and dates.
Collections are usually processed by duplicating context which encapsulates all tags matching that collection.
Templater will use reflection to analyze classes, but it can work also on dynamic data types such as dictionary/map.
Templater has special behavior for several data types, such as:
- image - injects image into the document
- nested array/DataTable - invokes dynamic resize feature of the Templater
- XML - can inject XML as-is
and several others (DateTime, multiline strings, ...).
Low level resize(tags, count) API is used for duplicating part of the document.
It can work for simple cases, such as single row in a table, but can be used for more complex ones:
- multiple rows - tags can span multiple rows, which will cause multi-row copying
- nested elements - tags can span multiple tables/lists which can be used for cloning complex document layouts
- formula rewriting - as formulas are moved around and copied, their expressions will be adjusted accordingly
- row/column styles - if possible styles will be maintained during horizontal or vertical resizing (horizontal resizing requires horizontal-resize metadata)
- pushdown/pushright - elements bellow/right of tags area will be moved according to builtin rules
- merge cells/named ranges/tables - influence push rules by extending the affected region
- XML binding - custom XML will be changed/updated when bound in Word
- streaming - streaming over collections is also supported
This repository contains various examples covering some of the features:
Templater has several extensibility points. Various plugins are embedded into library, while others can be registered during library initialization.
Examples:
- verbalize number into words
- insert QR code
- customize tag pattern
- custom transformation during navigation
- custom reflection processing
- overriding bultin plugins
- custom type processing
- runtime filtering
Q: How can I inject text with special color/bolding instead of plain (or pre-formatted) text into Templater?
A: You need to use XML to inject rich text into document (and format it appropriately to the target document format).
Q: Can I convert docx/xlsx/pptx to PDF?
A: Templater does not support converting documents to PDF. If MS Office can't be used to do PDF conversion there are various 3rd party libraries such as Aspose or Spire for PDF conversion. For low budget solutions headless LibreOffice can be used. Almost all non MS solutions have some pixel perfect issues :(. To ease the usage of LibreOffice there is a Dockerfile which will prepare the environment for easy PDF conversion. Templater does support digital signatures and can sign documents as an alternative to PDF in some cases
Q: Is this just a fancy mail-merge library?
A: Not at all. Templater can create really complex documents, but you might need to have a good knowledge of Word/Excel/PowerPoint to create such complex documents.
Q: How does Templater compare to Microsoft OOXML SDK?
A: OOXML SDK is a low level abstraction over Office document formats, while Templater is a high level abstraction over populating documents with data. Templater goal is to avoid writing code for creating reports, but instead bind provided data with an existing template.