HTML templates

You can create documents from HTML templates using Plumsail Documents. There are at least two ways to apply data to an HTML template:

This article explains HTML templates syntax.

General overview

HTML templates syntax in Plumsail Documents is quite similar to the syntax of popular JavaScript framework Handlebars. It supports if and each tags. It also makes it easy to reference nested values. Example:

{{Customer.Address.ZipCode}}

Template syntax supported in Plumsail Documents is geared towards building text and HTML documents. You can explicitly indicate when you want newlines. Example:

Hello, {{Customer.Name}}
{{#newline}}
{{#newline}}
{{#with Order}}
{{#if LineItems}}
Here is a summary of your previous order:
{{#newline}}
{{#newline}}
{{#each LineItems}}
    {{ProductName}}: {{UnitPrice:C}} x {{Quantity}}
    {{#newline}}
{{/each}}
{{#newline}}
Your total was {{Total:C}}.
{{#else}}
You do not have any recent purchases.
{{/if}}
{{/with}}

Placeholder Scope

The identifier is used to find a property with a matching name. If you want to print out the object itself, you can use the special identifier this:

Hello, {{this}}!!!

Some tags, such as each and with, change which object the values will be retrieved from.

If a property with the placeholder name can’t be found in the current scope, the name will be searched for at the next highest level.

The engine will automatically detect when an object is a dictionary and search for a matching key. In this case, it still needs to be a valid identifier name.

Nested Placeholders

If you want to grab a nested property, you can separate identifiers using a dot .:

{{Customer.Address.ZipCode}}

The ‘if’ tag

The if tag allows you to conditionally include a block of text.

Hello{{#if Name}}, {{Name}}{{/if}}!!!

The block will be printed if:

  • The value is a non-empty string.

  • The value is a non-empty collection.

  • The value isn’t the NUL char.

  • The value is a non-zero number.

  • The value evaluates to true.

The if tag has complimentary elif and else tags. There can be as many elif tags as desired but the else tag must appear only once and after all other tags.

{{#if Male}}Mr.{{#elif Married}}Mrs.{{#else}}Ms.{{/if}}

The ‘each’ tag

If you need to print out a block of text for each item in a collection, use the each tag:

{{#each Customers}}
Hello, {{Name}}!!
{{/each}}

Within the context of the each block, the scope changes to the current item. So, in the example above, Name would refer to a property in the Customer class.

Additionally, you can access the current index into the collection being enumerated using the index tag:

<ul>
{{#each Items}}
    <li class="list-item{{#index}}" value="{{Value}}">{{Description}}</li>
{{/each}}
</ul>

This will build an HTML list, building a list of items with Description and Value properties. Additionally, the index tag is used to create a CSS class with increasing numbers.

The ‘with’ tag

Within a block of text, you may refer to a same top-level placeholder over and over. You can cut down the amount of text by using the with tag.

{{#with Customer.Address}}
{{FirstName}} {{LastName}}
{{Line1}}
{{#if Line2}}
{{Line2}}
{{/if}}
{{#if Line3}}
{{Line3}}
{{/if}}
{{City}} {{State}}, {{ZipCode}}
{{/with}}

Here, the Customer.Address property will be searched first for the placeholders. If a property cannot be found in the Address object, it will be searched for in the Customer object and on up.

Date, time, and numeric formats

The templating engine uses standard format strings. You can find more information in Microsoft documentation:

And review a few examples to understand how it works:

Examples

Template

Data

Result

Date: {{date:dd/MM/yyyy}}
Date: {{date:MM/dd}}
Date: {{date:U}}
Number: {{num:C}}
Number: {{num:P}}
Number: {{num:N2}}
{
    "date": "2012-04-21T18:25:43-05:00",
    "num": 8
}
Date: 22 Apr 2012
Date: 04/22
Date: Saturday, April 21, 2012 11:25:43 PM
Number: $8.00
Number: 800.00%
Number: 8.00

Note

If you create PDFs from HTML templates, you may need to use custom fonts and to convert some languages characters correctly. Please, check this article to learn how to achieve that.

Note

The template engine is implemented based on mustache#