Work with DotLiquid

14 min

What Is DotLiquid?

DotLiquid is an HTML templating engine used in {user["product-name"]} website views. Additional info can be found at DotLiquid markup.

How does Optimizely {user["product-name"]} use DotLiquid?

For {user["product-name"]} versions 4.2 and prior, all views were implemented in Razor, which allows developers access to any .net code as well as our libraries. Beginning with {user["product-name"]} 4.3, access to the filesystem and backend libraries is restricted in order to support our SaaS based product, {user["product-name"]} Cloud. As a result, {user["product-name"]} only allows standard HTML and DotLiquid in website views. This still gives developers access to the objects provided to the view and allowing for basic HTML templating.

Important The syntax and documentation found for standard DotLiquid will work except for one difference: the default {{ }} syntax has been replaced by [[ ]] in an effort to avoid conflict with Angular code, which is frequently used in {user["product-name"]} views.

{user["product-name"]} DotLiquid tags

{user["product-name"]} has several custom tags to help facilitate common functionality.

EmailRegex

Renders an angular compatible regex for validating emails.

[% emailRegex %]

PartialView

Renders partial views from .WebProject/Themes/[ThemeName]/Views/Directives/[FolderName]/[ViewName].

[% partialView '\[FolderName\]-\[ViewName\]' %\]

Note FolderName is optional

PhoneRegex

Renders an angular compatible regex for validating phone numbers.

[% phoneRegex %]

SiteMessage

Gets a message from the MessageProvider with the message name as the first argument in quotes (single or double are both valid). Optionally it takes a default value as a second string argument. If it is used within single quotes in html it takes an optional last parameter named "EscapeSingleQuotes" that will escape all single quotes in the message returned.

[% siteMessage 'MessageName' %]
[% siteMessage 'MessageName' EscapeSingleQuotes %]
[% siteMessage 'MessageName' 'DefaultValue' %]
[% siteMessage 'MessageName' 'DefaultValue' EscapeSingleQuotes %]

Translate

Translates the provided string value using the TranslationLocalizer. If it is used within single quotes in html it takes an optional last parameter named "EscapeSingleQuotes" that will escape all single quotes in the message returned.

[% translate 'Phrase To Translate' %]

UrlForPage

Renders a url for the page type specified. The first argument is the Page type. ie HomePage, CartPage, OrderDetailPage

[% urlForPage 'HomePage' %]

Zone

Renders the html required to define a zone.

[% zone 'Zone Name' %]

Custom DotLiquid tags

DotLiquid provides the ability to create custom tags. To do this, you need to create a class that inherits from the DotLiquid.Tag class. You can use the "Create your own tags" section at DotLiquid for Developers as a reference.

Create a class that inherits from DotLiquid.Tag. Use the Initialize method to validate and capture arguments. Use the Render method to write content for the custom tag. Below is an example of a custom tag that prints the first argument inside an <h1> element.

public class MyCustomTag : DotLiquid.Tag
{
  // Matches the patterns:
  // 'AnyLettersAnyCase'
  // "AnyLettersAnyCase"
  private static readonly Regex ArgumentRegex = new Regex("^(['\"])([a-zA-Z]+)\\1$");
  private string arg1 = string.Empty;
  public override void Initialize(string tagName, string markup, List<string> tokens)
  {
    markup = markup.Trim();
    this.ValidateMarkup(markup);
    this.CaptureArguments(markup);
       base.Initialize(tagName, markup, tokens);
  }
     private void ValidateMarkup(string markup)
  {
    if (!ArgumentRegex.IsMatch(markup))
    {
      throw new ArgumentException("The markup for the myCustomTag tag is incorrect. The expected form is [% myCustomTag 'arg1' %].", nameof(markup));
    }
  }
     private void CaptureArguments(string markup)
  {
    this.arg1 = ArgumentRegex.Match(markup).Groups[2].Value;
  }
     public override void Render(Context context, TextWriter result)
  {
    result.Write($"<h1>{this.arg1}</h1>");
  }
}

Next, you need to register your custom tag with DotLiquid, so it can properly parse and render it within any views. You can register your custom tag in the PostStartup method of the ~/App_Start/Startup.cs file using the following code.

Template.RegisterTag<MyCustomTag>("myCustomTag");

Finally, rebuild your solution. You should now be able to use your custom tag in a view.

[% myCustomTag 'arg1' %]