DocxTemplater 2.3.0-alpha

DocxTemplater

DocxTemplater is a library to generate docx documents from a docx template. The template can be bound to multiple datasources and be edited by non-programmers. It supports placeholder replacement and loops and images

Features:

• Variable Replacement
• Collections - Bind to collections
• Conditional Blocks
• Dynamic Tables - Columns are defined by the datasource
• HTML Snippets - Replace placeholder with HTML Content
• Images - Replace placeholder with Image data

Quickstart

Create a docx template with placeholder syntax

This Text: {{ds.Title}} - will be replaced

Open the template, add a model and store the result to a file

   var template = DocxTemplate.Open("template.docx");
   template.BindModel("ds", new { Title = "Some Text"});
   template.Save("generated.docx");

The generated word document then contains

This Text: Some Text - will be replaced

Install DocxTemplater via NuGet

If you want to include DocxTemplater in your project, you can install it directly from NuGet

To install DocxTemplater, run the following command in the Package Manager Console

PM> Install-Package DocxTemplater

or for Image support

PM> Install-Package DocxTemplater.Images

Placeholder Syntax

A placeholder can consist of three parts: {{property}:formatter(arguments)}

• property: the path to the property in the datasource objects.
• formatter: formatter applied to convert the model value to openxml (ae. toupper, tolower img format etc)
• arguments: formatter arguments - some formatter have arguments

The syntax is case insensitive

Quick Reference: (Expamples)

Collections

To repeat document content for each item in a collection the loop syntax can be used: {{#<collection>}} .. content .. {{<collection>}} All document content between the start and end tag is rendered for each element in the collection.

{{#Items}} This text {{Items.Name}} is rendered for each element in the items collection {{/items}}

This can be used, for example, to bind a collection to a table. In this case, the start and end tag has to be placed in the row of the table

This template bound to a model:

            var template = DocxTemplate.Open("template.docx");
            var model = new
            {
                Items = new[]
                {
                    new { Name = "John", Position = "Developer" },
                    new { Name = "Alice", Position = "CEO" }
                }
            };
            template.BindModel("ds", model);
            template.Save("generated.docx");

will render a table row for each item in the collection

Separator

If you want to render a separator between the items in the collection, you can use the separator syntax:

{{#Items}} This text {{.Name}} is rendered for each element in the items collection {{:s:}} This is rendered between each elment {{/items}}

Conditional Blocks

Show or hide a given section depending on a condition: {?{<condition>}} .. content .. {{/}} All document content between the start and end tag is rendered only if the condition is met

{?{Item.Value >= 0}}Only visible if value is >= 0
{{:}}Otherwise this text is shown{{/}}

Formatters

If no formatter is specified, the model value is converted into a text with "ToString".

This is not sufficient for all data types. That is why there are formatters that convert text or binary data into the desired representation

The formatter name is always case insensitive

String Formatters

• ToUpper, ToLower

FormatPatterns

Any type that implements IFormattable can be formatted with the standard format strings for this type

See: Standard date and time format strings Standard numeric format strings .. and many more

Examples: {{SomeDate}:format(d)} ----> "6/15/2009" (en-US) {{SomeDouble}:format(f2)} ----> "1234.42" (en-US)

Image Formatter

NOTE: for the Image formatter the nuget package DocxTemplater.Images is required

Because the image formatter is not standard, it must be added

var docTemplate = new DocxTemplate(fileStream);
docTemplate.RegisterFormatter(new ImageFormatter());

The image formatter replaces a placeholder with an image stored in a byte array

The placeholder can be placed in a TextBox so that the end user can easily adjust the image size in the template. The size of the image is then adapted to the size of the TextBox.

The stretching behavior can be configured

Error Handling

If a placeholder is not found in the model an exception is thrown. This can be configured with the ProcessSettings

var docTemplate = new DocxTemplate(memStream);
docTemplate.Settings.BindingErrorHandling = BindingErrorHandling.SkipBindingAndRemoveContent;
var result = docTemplate.Process();

Culture

The culture used to format the model values can be configured with the ProcessSettings

var docTemplate = new DocxTemplate(memStream, new ProcessSettings()
{
    Culture = new CultureInfo("en-us")
});
var result = docTemplate.Process();