Fluid Liquid Template Engine for .NET

Fluid provides a Visitor pattern to inspect or modify the Abstract Syntax Tree (AST) of a template.

Visiting a template

Use Fluid.Ast.AstVisitor to traverse the template. This is useful for security checks (e.g., verifying if a specific identifier is accessed) or auditing.

Rewriting a template

Use Fluid.Ast.AstRewriter to create a new version of the template with modified nodes. For example, you can replace one filter with another (e.g., replacing plus with minus).

Automatic processing via TemplateParsed

To apply visitors or rewriters to all templates (including includes and partials) automatically, use the TemplateParsed callback on TemplateOptions. This ensures the modified version is cached, improving performance.

public class ReplacePlusFiltersVisitor : AstRewriter
{
    protected override Expression VisitFilterExpression(FilterExpression filterExpression)
    {
        if (filterExpression.Name == "plus")
        {
            return new FilterExpression(filterExpression.Input, "minus", filterExpression.Parameters);
        }
        return filterExpression;
    }
}

// Usage
var template = new FluidParser().Parse("{{ 1 | plus: 2 }}");
var visitor = new ReplacePlusFiltersVisitor();
var changed = visitor.VisitTemplate(template);
var result = changed.Render(); // writes -1

Fluid implements Shopify money filters, but they must be explicitly registered in TemplateOptions.

Registration:

var options = new TemplateOptions();
options.Filters.WithMoneyFilters();

Available Filters:

• money: Formats as currency (e.g., $1,134.65)
• money_with_currency: Formats with currency code (e.g., $1,134.65 USD)
• money_without_currency: Formats without currency symbol (e.g., 1,134.65)
• money_without_trailing_zeros: Removes trailing zeros (e.g., $10)

Configuration Options:

• Cultures/Currencies: Formatting is derived from TemplateOptions.CultureInfo. You can set a default currency via options.MoneyOptions.Currency = "EUR"; or pass a currency to the filter: {{ 10 | money: 'GBP' }}.
• Custom Currencies: Add new currencies to options.MoneyOptions.Currencies using MoneyCurrency.
• Amounts in Cents: If your data uses cents (like Shopify), set options.MoneyOptions.AmountsInCents = true; to automatically divide inputs by 100.
• Custom Formats: Use MoneyOptions.MoneyFormat and MoneyOptions.MoneyWithCurrencyFormat with Shopify-style placeholders like {{amount}}, {{currency}}, and {{currency_symbol}}.

To achieve maximum performance with Fluid, follow these three best practices:

1. Cache IFluidTemplate instances: Parsing is expensive. Instead of calling FluidParser.Parse() every time, cache the resulting IFluidTemplate instance. Use a unique key like the template name or content. It is recommended to use a singleton IMemoryCache with size limits and eviction policies to prevent unbounded memory growth. IFluidTemplate is thread-safe for read access.

2. Reuse TemplateOptions: TemplateOptions contains shared state like property resolutions and lambdas. These are designed to be reused across multiple renderings. You can declare them as static or register them as a singleton in your DI container. TemplateOptions is thread-safe for read access.

3. Reuse FluidParser: Instantiating a FluidParser is an expensive operation. Create one instance and reuse it throughout your application lifecycle (e.g., as a static instance or a singleton in DI).

Summary of Thread Safety:

• IFluidTemplate: Thread-safe for read access.
• TemplateOptions: Thread-safe for read access.
• FluidParser: Should be reused (singleton/static).

You can use TemplateOptions.ValueConverters to intercept .NET objects and return different values than those provided by the source model.

• To return a custom value (like a formatted string) instead of the original type, return a FluidValue (e.g., StringValue).
• To indicate that no conversion should be applied (allowing Fluid to use its default mapping), return null.

You can also use this to wrap objects in a proxy class that inherits from ObjectValueBase to implement custom logic for specific property names.

// Example: Converting DateTime to a custom string
var options = new TemplateOptions();
options.ValueConverters.Add(o => o is DateTime d ? new StringValue($"This is a date time: {d}") : null);

// Example: Using a proxy to add virtual properties to an object
private class PersonValue : ObjectValueBase
{
    public PersonValue(Person value) : base(value) { }

    public override ValueTask<FluidValue> GetValueAsync(string name, TemplateContext context)
    {
        if (name == "Bingo")
        {
          return new StringValue("Hello, World!");
        }
        return base.GetValueAsync(name, context);
    }
}

var options = new TemplateOptions();
options.ValueConverters.Add(o => o is Person p ? new PersonValue(p) : null);