Quick Start

Updated for version 0.9.5

A Simple Template

Here's a simple template that renders a variable in HTML:

<div>{{myvariable}}</div>

The C# code to render this template in Liquid.NET looks like this:

// The TemplateContext stores values that the template can render 
// (along with other values).
ITemplateContext ctx = new TemplateContext();

// Any values that you want to put into the TemplateContext in Liquid.NET 
// are put into wrappers.  For example, the call to the static factory 
// LiquidString.Create(String value) will create a string-wrapper of the 
// type LiquidString.
ctx.DefineLocalVariable("myvariable", LiquidString.Create("Hello World!"));

// You can generate a template with "LiquidTemplate.Create(String template)".
// Values that are rendered are wrapped in double-parentheses: "{{" and "}}".
var parsingResult = LiquidTemplate.Create("<div>{{myvariable}}</div>");
Console.WriteLine(parsingResult.LiquidTemplate.Render(ctx));

==> "<div>Hello World!</div>"

Render a Simple Collection with a "For" Tag

Liquid can render a "collection" of values like this:

<ul>
{% for myitem in mycollection %}
   <li>{{ myitem }}</li>
{% endfor %}
</ul>

ITemplateContext ctx = new TemplateContext();

// You can create an array using the IEnumerable array-creation literal.
// Here, each element is a numeric type.
ctx.DefineLocalVariable("mycollection", new LiquidCollection{{ 
   LiquidNumeric.Create(2),
   LiquidNumeric.Create(4),
   LiquidNumeric.Create(6)
}};

// A tag uses the delimiters "{%" and "%}".
var parsingResult= LiquidTemplate.Create("<ul>{% for item in items %}" +
    "<li>{{item}}</li>" +
    "{% endfor %}</ul>");
Console.WriteLine(parsingResult.LiquidTemplate.Render(ctx));

==> "<ul><li>2</li><li>4</li><li>6</li></ul>"

Here we used a Liquid tag. A tag usually wraps html in some way. In this case, it wraps the contents of a for loop. A tag may have no closing delimiter, but when it does, it will look like {% end____ %}.

Render an Object in a Template

In Liquid.NET, an object is represented by a LiquidHash (which implements IDictionary). If you're wondering where liquid "drops" are, you can stop looking---they aren't necessary in .Net.

ITemplateContext ctx = new TemplateContext();

// Create a hash with two fields, "first" and "last"
var nameHash = new LiquidHash
{
    {"first", LiquidString.Create("Tobias")},
    {"last", LiquidString.Create("Lütke")}
};

// Create a hash with two fields---one string, and one hash.
ctx.DefineLocalVariable("greeting", new LiquidHash
{
    {"address", LiquidString.Create("Hello")},
    {"name", nameHash}
});

// You can reference arbitrarily nested hashes using dots
var parsingResult= LiquidTemplate.Create("You said '{{ greeting.address }} "+ 
    "{{ greeting.name.first }} {{ greeting.name.last }}'");

Console.WriteLine(parsingResult.LiquidTemplate.Render(ctx));

==> "You said 'Hello Tobias Lütke'"

Alter values with a filter.

You can change a value with a filter.

{{ resultcount }} {{ pluralize: 'item', 'items' }} were found 
for '{{searchterm | downcase}}'.

// TemplateContext can be initialized fluently.
// Add .WithAllFilters() to include the filters.
ITemplateContext ctx = new TemplateContext()
        .WithAllFilters()
        .DefineLocalVariable("resultcount", LiquidNumeric.Create(42))
        .DefineLocalVariable("searchterm", LiquidString.Create("MiXeDcAsE"));

var parsingResult= LiquidTemplate.Create("{{ resultcount }} " +
    "{{ resultcount | pluralize: 'item', 'items' }} were found " +
    "for '{{searchterm | downcase}}'.");

Console.WriteLine(parsingResult.LiquidTemplate.Render(ctx));

=> "42 items were found for 'mixedcase'."

Handle Parsing Errors

There are two kinds of errors in Liquid.NET: parsing errors and rendering errors. These are returned alongside the results produced by LiquidTemplate.Create() and LiquidTemplate.Render().

Parsing errors can occur when you're parsing a liquid template:

var template = "This filter delimiter is not terminated: {{ myfilter";
var parsingResult= LiquidTemplate.Create(template);            
String error = String.Join(",", parsingResult.ParsingErrors
    .Select(x => x.ToString()));
Console.WriteLine(error):

=> "line 1:52 Missing '}}'"

The result here shows that on line 1, character 52, it was expecting to find the matching '}}' for the filter.

Handle Rendering Errors

At rendering time, you can get both rendering and parsing errors. (Parsing errors may come from an include tag.) This code handles just the rendering errors:

ITemplateContext ctx = new TemplateContext().WithAllFilters();
String template = "Divide by zero result in: {{ 1 | divided_by: 0}}";
var parsingResult = LiquidTemplate.Create(template);
var renderingResult = parsingResult.LiquidTemplate.Render(ctx);
String error = String.Join(",", renderingResult.RenderingErrors
    .Select(x => x.Message));

Console.WriteLine("The ERROR was : " + error);
Console.WriteLine("The RESULT was : " + renderingResult.Result);

==> The ERROR was : Liquid error: divided by 0
==> The RESULT was : Divide by zero result in: Liquid error: divided by 0

Note that the template is still parsed, with the error message rendered.