ZetCode

C# Scriban

last modified March 30, 2022

C# Scriban tutorial shows how to usie Scriban template engine in C#.

Scriban template engine

A template engine or template processor is a library designed to combine templates with a data model to produce documents. Template engines are often used to generate large amounts of emails, in source code preprocessing, or producing dynamic HTML pages.

We create a template engine, where we define static parts and dynamic parts. The dynamic parts are later replaced with data. The rendering function later combines the templates with data. A template engine is used to combine templates with a data model to produce documents.

Scriban uses {{ }} for code blocks and {%{ }%} for escape blocks. Any other text is considered as a text block and simply output as is.

The Template.Parse method parses the text data into a template and the Template.Render renders the template into the final output using the provided data model.

$ dotnet add package Scriban

We need to add the Scriban package to our projects.

Scriban simple example

The following is a simple Scriban example.

Program.cs
using Scriban;

var name = "John Doe";

var tpl = Template.Parse("Hello {{name}}!");
var res = tpl.Render(new { name = name });

Console.WriteLine(res);

The program prints a small message to the console.

var tpl = Template.Parse("Hello {{name}}!");

The Template.Parse method parses the specified scripting text into a template. With {{ }} we output the content of the name variable.

var res = tpl.Render(new { Name = name });

The Render method renders the template using the specified object model.

$ dotnet run
Hello John Doe!

In the next example, we pass two variables to the template engine.

Program.cs
using Scriban;

var name = "John Doe";
var occupation = "gardener";

var txt = "{{name}} is a {{occupation}}";
var tpl = Template.Parse(txt);
var res = tpl.Render(new { name, occupation });

Console.WriteLine(res);

The program prints a message using data from two variables: name and occupation.

$ dotnet run
John Doe is a gardener

Scriban for loop

Loops are created with for directive.

Program.cs
using Scriban;

string[] words = { "sky", "blue", "falcon", "book", "ocean", "dog" };

var html = @"
<ul>
{{- for word in words }}
    <li> {{ word }} </li>
{{- end }}
</ul>
";

var tpl = Template.Parse(html);
var res = tpl.Render(new { words = words });

Console.WriteLine(res);

The example uses the for directive to output an array of words into an HTML list.

{{- for word in words }}
    <li> {{ word }} </li>
{{- end }}

We iterate over the array of words. The - character strips white space characters on the left.

$ dotnet run 
<ul>
    <li>sky</li>
    <li>blue</li>
    <li>falcon</li>
    <li>book</li>
    <li>ocean</li>
    <li>dog</li>
</ul>

Scriban string functions

We can use several string functions in the templates.

Program.cs
using Scriban;

var msg = "an old falcon";

var data = @"
{{ msg | string.capitalize }}
{{ msg | string.upcase }}
The message has {{ msg | string.size }} characters.
The message has {{ msg | string.split ' ' | array.size }} words.
";

var tpl = Template.Parse(data);
var res = tpl.Render(new { msg = msg });

Console.WriteLine(res);

We have a string message. We apply several string functions on the message.

{{ msg | string.capitalize }}
{{ msg | string.upcase }}

We capitalize and upcase the message.

The message has {{ msg | string.size }} characters.

We count the number of characters in the message.

The message has {{ msg | string.split ' ' | array.size }} words.

We count the number of words in the message. In addition to string.split function, we use the array.size to get the size of the array of split strings.

$ dotnet run
An old falcon
AN OLD FALCON
The message has 13 characters.
The message has 3 words.

Scriban array functions

Scriban supports array functions.

Program.cs
using Scriban;

int[] vals = { 2, 1, -3, 0, -1, -2, 3 };

var data = @"
The array has {{ vals.size }} elements
First element: {{ vals[0] }}
Last element: {{ vals[-1] }}
Sorted elements: {{ vals | array.sort}}
";

var tpl = Template.Parse(data);
var res = tpl.Render(new { vals = vals });

Console.WriteLine(res);

We have an array of integers. With built-in array functions, we count the elements and sort them.

$ dotnet run 
The array has 7 elements
First element: 2
Last element: 3
Sorted elements: [-3, -2, -1, 0, 1, 2, 3]

Scriban conditions

We can use if/else if/else conditions in templates.

Program.cs
using Scriban;

string?[] names = { "John", "Nelly", null, "George" };

var data = @"
{{- for name in names -}}
  {{ if !name  }}
Hello there!
  {{ else }}
Hello {{name}}!
  {{ end }}
{{- end }}";

var tpl = Template.Parse(data);
var res = tpl.Render(new { names = names });

Console.WriteLine(res);

We have an array of names. With the if condition, we check if the element is not null.

$ dotnet run
Hello John!

Hello Nelly!

Hello there!

Hello George!

Scriban read template from file

In the following example, we read the tempate file from a file.

users.tpl
<table>
    <thead>
    <tr>
        <th>Name</th>
        <th>Occupation</th>
    </tr>
    </thead>
    <tbody>
    {{- for user in users }}
    <tr>
        <td>{{ user.name }}</td>
        <td>{{ user.occupation }}</td>
    </tr>
    {{- end }}
    </tbody>
</table>

The template file outputs data in an HTML table.

Program.cs
using Scriban;

var users = new List<User>
{
    new ( "John Doe", "gardener"),
    new ( "Roger Roe", "driver"),
    new ( "Lucy Smith", "teacher")
};

var fileName = "users.tpl";
var data = File.ReadAllText(fileName);

var tpl = Template.Parse(data);
var res = tpl.Render(new { users = users });

Console.WriteLine(res);

record User(string Name, string Occupation);

The data is stored in a list of records. The template file is loaded with the File.ReadAllText method.

$ dotnet run 
<table>
    <thead>
    <tr>
        <th>Name</th>
        <th>Occupation</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td>John Doe</td>
        <td>gardener</td>
    </tr>
    <tr>
        <td>Roger Roe</td>
        <td>driver</td>
    </tr>
    <tr>
        <td>Lucy Smith</td>
        <td>teacher</td>
    </tr>
    </tbody>
</table>

In this article we have worked with the Scriban template engine in C#.

List all C# tutorials.