Liquid.NET for Developers

Although the Liquid.NET templating language is very close to Shopify Liquid, the Liquid.NET C# code is very different from the Shopify Ruby implementation.

The Quick Start Guide is a good place to start to see what Liquid.NET C# code looks like.

Basic Template Parsing & Rendering

The three basic steps to generate a liquid template are:

1. Create a LiquidTemplate from a string using LiquidTemplate.Create()
2. Create a context that contains the template's state, including your data
3. Merge your data from the context into the LiquidTemplate using LiquidTemplate.Render()

// create a template context that knows about the standard filters,
// and define a string variable "myvariable"
var ctx = new TemplateContext()
    .WithAllFilters()
    .DefineLocalVariable("myvariable", LiquidString.Create("Hello World"));

// parse the template and check for errors
var parsingResult = LiquidTemplate.Create("<div>{{myvariable}}</div>");

if (parsingResult.HasParsingErrors)
{
    MyErrorHandler(parsingResult.ParsingErrors);
    return;
}

// merge the variables from the context into the template and check for errors
var renderingResult = parsingResult.LiquidTemplate.Render(ctx);
if (renderingResult.HasParsingErrors)
{
    HandleErrors(renderingResult.ParsingErrors);
    return;
}
if (renderingResult.HasRenderingErrors)
{
    HandleErrors(renderingResult.RenderingErrors);
    return;
}

Console.WriteLine(renderingResult.Result);

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

Syntactic Sugar for Error Handling

That first example has a lot of ceremony to handle errors. Here is a more concise way of expressing the same thing (in 0.9.7):

var ctx = new TemplateContext()
    .WithAllFilters()
    .DefineLocalVariable("myvariable", LiquidString.Create("Hello World"));

var errors = new List<LiquidError>();

// Note that you will still get a best-guess LiquidTemplate, even if you encounter errors.
var liquidTemplate = LiquidTemplate.Create("<div>{{myvariable}}</div>")
    .OnParsingError(errors.Add)
    .LiquidTemplate;

if (parsingErrors.Any()) {
    // handle the parsing errors, return
}

// The final String output will still be available in .Result, 
// even when parsing or rendering errors are encountered.
var renderingResult = liquidTemplate.Render(ctx)
    .OnAnyError(errors.Add) // also available: .OnParsingError, .OnRenderingError
    .Result;

Console.WriteLine(renderingResult);

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

Types

Types in liquid are numeric, boolean, string, collection, hash, date, and the special type range. These are represented with C# classes that implement ILiquidValue. There is also the value nil, which has no liquid type.

liquid	C#
boolean	LiquidBoolean
numeric	LiquidNumeric
date	LiquidDate
string	LiquidString
collection	LiquidCollection
hash	LiquidHash
range*	LiquidRange

Ranges are currently only available in a few places---most of the rest of this discussion doesn't apply to them. More on this later.

LiquidHashes and LiquidCollections are heterogeneous, meaning that a collection can hold a mix of types, and although the keys of a hash are always strings, a value in a hash can also be of any type.

A numeric has an underlying C# type, which is int, long, decimal or BigInteger. You can create a LiquidNumeric with the static constructor LiquidNumeric.Create(val). This means that if you create a numeric value with the decimal "3.00", it will render as "3.00". If you do math with two numeric values, it will attempt to use the precision of the most precise value, so an "int" LiquidNumeric times a "decimal" LiquidNumeric will yield a decimal LiquidNumeric.

Filters

See How to Write a Filter for more details.

Tags

See How to Write a Tag or Block for more details.