Skip to content

Simplify.Templates

Jump to bottom
Alexanderius edited this page Jul 15, 2025 · 8 revisions

Simplify.Templates Documentation

Provides ITemplate interface, Template class, and TemplateBuilder class for working with text templates.

With Simplify.Templates, you can easily load text templates, localize them, insert data, and get the generated result.

Available at NuGet as binary package

Quick Start

Load the template from a file located in the current assembly directory:

var tpl = TemplateBuilder
    .FromLocalFile("TestTemplate.tpl")
    .Build();

The TestTemplate.tpl file:

<html>
<body>
<div>{SomeVariable}</div>
<div>{Items}</div>
</body>

Setting data into the template variables:

tpl.Set("SomeVariable", "footext");

tpl.Add("Items", "1")
    .Add("Items", "2")
    .Add("Items", "3");

Getting the template text:

var str = tpl.Get();

str will contain:

<html>
<body>
<div>footext</div>
<div>123</div>
</body>

Other Ways of Template Loading

To choose how to load a template, use respective TemplateBuilder static methods:

  • Loading template from a string: FromString("some string")
  • Loading template from a file: FromFile("D:\SomeDir\SomeFile.txt")
  • Loading template from a file located in the current assembly directory: FromLocalFile("SomeFile.txt")
  • Loading template from current assembly embedded resources: FromCurrentAssembly("FilePath.Filename.tpl") or FromCurrentAssembly("FilePath/Filename.tpl")
  • Loading template from specified assembly embedded resources: FromAssembly("FilePath.Filename.tpl", myAssembly)

Template Localization

If you want a template to be localizable, create an XML file in the same directory as the template file.

Files should be named like FooTemplate.tpl.en.xml if the template file name is FooTemplate.tpl. For embedded templates, it should be named like FooTemplate.tpl-en.xml.

You can keep several files for each language you want to localize, for example:

FooTemplate.tpl
FooTemplate.tpl.en.xml
FooTemplate.tpl.de.xml
FooTemplate.tpl.ru.xml

Localization file FooTemplate.tpl.de.xml example:

<?xml version="1.0" encoding="utf-8"?>
<items>
    <item name="LocalizableVariable" value="Test" />
</items>

Localization file FooTemplate.tpl.en.xml example:

<?xml version="1.0" encoding="utf-8"?>
<items>
    <item name="LocalizableVariable" value="Test default" />
    <item name="LocalizableVariable2">
        <a href="#">localizable data default</a>
    </item>
</items>

Template file FooTemplate.tpl example:

<html>
<body>
<div>{LocalizableVariable}</div>
<div>{LocalizableVariable2}</div>
</body>

To perform localization, use respective fluent methods: Localizable, LocalizableFromCurrentThreadLanguage.

There are two language code parameters: the current language and the default language.

At the time the template builds, the current language localization file will be inserted into the template, followed by the default localization file. If some localizable values do not exist in the current localization file, they will be inserted from the default localization file.

To use Thread.CurrentThread.CurrentCulture.TwoLetterISOLanguageName as the current language code, use the LocalizableFromCurrentThreadLanguage method.

Output example:

var tpl = TemplateBuilder
    .FromLocalFile("FooTemplate.tpl")
    .Localizable("de", "en")
    .Build();

var str = tpl.Get();

str will contain:

<html>
<body>
<div>Test</div>
<div><a href="#">localizable data default</a></div>
</body>

Building Items List Example

The MasterTemplate.tpl file:

<html>
<body>
{Links}
</body>

The FooLinkItem.tpl file:

<a href="http://foolink/{ItemID}">{MyLinkLabel} {ItemID}</a><br />

The FooLinkItem.tpl.en.xml file:

<?xml version="1.0" encoding="utf-8"?>
<items>
    <item name="MyLinkLabel" value="My item" />
</items>

Building links list:

class MyItem
{
    public int ID { get; set; }
}

...

var items = new List<MyItem> { new MyItem {ID = 1}, new MyItem {ID = 2}, new MyItem {ID = 3} };

var tpl = TemplateBuilder
    .FromFile("Templates/MasterTemplate.tpl")
    .Build();

var itemTpl = TemplateBuilder
    .FromFile("Templates/FooLinkItem.tpl")
    .Build();

foreach (var item in items)
{
    itemTpl.Set("ItemID", item.ID);

    // Adding our generated item data to the master template and rolling it back to initial, but localized state
    tpl.Add("Links", itemTpl.GetAndRoll());
}

var str = tpl.Get();

str will contain:

<html>
<body>
<a href="http://foolink/1">My item 1</a><br />
<a href="http://foolink/2">My item 2</a><br />
<a href="http://foolink/3">My item 3</a><br />
</body>

Model Binding Example

The MyTemplate.tpl file:

{Prop1}
{Prop2}
{Prop3}

The model:

public class MyClass
{
    public string Prop1 { get; set; }
    public int Prop2 { get; set; }
    public DateTime Prop3 { get; set; }
}

Setting model to template:

var obj = new MyClass {Prop1 = "Foo", Prop2 = 5, Prop3 = new DateTime(2014, 09, 13)};

var tpl = TemplateBuilder
    .FromFile("MyTemplate.tpl")
    .Build();

tpl.Model(obj).With(x => x.Prop3, x => x.ToString("dd.MM.yyyy")).Set();

var str = tpl.Get();

str will contain:

Foo
5
13.09.2014
Clone this wiki locally