Templates

Templates provide a simple way of content generation using well-known Razor language syntax (see cheat-sheet below). They are very useful for generating content like email notifications, documents, contracts, etc.

Creating a template

Template code language

This setting is primarily about developer's comfort during preparation of a template.

Language	Syntax highlighting	Preview	Usage
None	No	No	Arbitrary strings you need to generate.
Html	HTML + Razor	Yes	Html pages, snippets. Useful for emails.
Markdown	MD + Razor	Yes	Markdown texts, usually converted into HTML later.

Model type

Model type defines input which the template receives. It's available as Model variable inside the model.

Type	C# type of Model	Usage
Object	Object	Arbitrary models, often used for custom classes or for templates without a model
String	String	Useful for nesting templates
String Enumerable	IEnumerable<string>	Useful for nesting templates
Entity	EntityType	Templates for entity
Entity Enumerable	IEnumerable<EntityType>	Templates for entity collection
Aspect	AspectType	Templates for entity inheriting an aspect
Aspect Enumerable	IEnumerable<AspectType>	Templates for collection of entities which inherit an aspect

Using the Object Model

The object model allows you to pass any arguments you need. To do this, create a class or record with the desired attributes, and then cast the model as the class or record instance in the template.

Ensure the attributes are correct, as this is not checked at compile time.

Usage

Every template you define is accessible through App.Templates object. Each template has a Render(model) method which requires different input based on selected Model Type.

MyEntity entity = db.MyEntitySet.First();
string rendered = App.Templates.MyTemplate.Render(entity);

Master template

Common use-case of templates is that you have one master template which contains eg. common header and footer and then generate inner content with various smaller templates. This setup is usually done by using String model template which acts as a Master. Inside this master template is following code:

...proceeding content...
@Html.Raw(Model)
...succeeding content...

Then you use the master template like this:

// Inner content    
MyEntity entity = db.MyEntitySet.First();
string rendered = App.Templates.MyTemplate.Render(entity);

string wholePage = App.Templates.MyMasterTemplate.Render(rendered);

Razor language

Razor language is templating language which allows you to embed custom logic into a template. With Razor you can add loops, conditions and even custom C# code.

Syntax/Sample	Razor
Mixing expressions and text	Hello @name!
Expression (Html Encoded)	<span>@Model.Message</span>
Expression (Unencoded)	<span>@Html.Raw(Model.Message)</span>
Explicit Expression	<span>ISBN@(isbnNumber)</span>
Calling method	@(MyClass.MyMethod<AType>()) Code Block | @{ int x = 123; string y = "foobar"; }
Iteration rendering	@foreach (var item in Model.items) { <span>@item.Prop</span> }
Conditional rendering	@if (foo) { <span>Plain Text</span> }
Escaping the @ sign	Hi mark@@example.com

Accessing the resources

You can access app resources in Razor code. Below is a simple example of how to include an image in a template:

<img class="container" src="data:image/png;base64,@App.Resources.my_image_jpg"/>

Using custom fonts

Another type of resource you can embed in the templates is a custom font. To add a font, add it as an Application resource. To embed the font, add the following to the HTML document as a style.

After data: follows the MIME type and the actual font data.

@font-face{
       font-family:MyFontName;
       font-weight:400;
       font-style:normal;
       src:url(data:application/font-woff;base64,@App.Resources.MyFont)
}

The MIME type must be adjusted to match the font format. In the example above, WOFF is used; however, more types can also be used, and they commonly are.

Font format	MIME type
Web Open Font Format (WOFF)	application/font-woff
TrueType (TTF)	application/x-font-truetype
OpenType (OTF)	application/x-font-opentype
SVG	image/svg+xml

Below is a full example:

@{
    var fontb64 = Convert.ToBase64String(App.Resources.BebasNeue_Regular_ttf.Content);
}

<!DOCTYPE html>
<html lang="cs">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Example Document</title>
    <style>
       @@font-face{
           font-family:BebasNeue;
           font-weight:400;
           font-style:normal;
           src:url(data:application/x-font-truetype;base64,@fontb64);
       }

        html, body {
           font-family: 'BebasNeue', serif;
           margin: 0;
           padding: 0;
       }
    </style>
</head> 

Note the @ symbol is escaped, as the @ needs to be written to the HTML.