Loading...
Area: Episerver B2B Commerce

Working with DotLiquid in Classic

Recommended reading 

Overview

What Is It?

DotLiquid is an HTML templating engine used in Epi B2B Commerce website views. Additional info can be found on DotLiquid at http://dotliquidmarkup.org.

How Is Epi B2B Commerce Using It?

For Epi B2B Commerce 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 Epi B2B Commerce 4.3, access to the filesystem and backend libraries is restricted in order to support our SaaS based product, Epi B2B Commerce Cloud. As a result, Epi B2B Commerce 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 Epi B2B Commerce views.

Epi B2B Commerce DotLiquid Tags

Epi B2B Commerce has several custom tags to help facilitate common functionality.

EmailRegex

Renders an angular compatible regex for validating emails.

[% emailRegex %]

NavigationMenu

Renders the navigation menu.

[% navigationMenu %]

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. In order 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 https://github.com/dotliquid/dotliquid/wiki/DotLiquid-for-Developers as a reference.

  1. 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>");
        }
    }
  2. Next, you need to register your custom tag with DotLiquid, so it can properly parse and render it within any views. You will need to create your startup file in the extensions project.
        [BootStrapperOrder(101)]
    public class RegisterCustomDotLiquidTags : IStartupTask
    {
    public void Run(IAppBuilder app, HttpConfiguration config)
    {
    Template.RegisterTag<SomeCustomTag>("someCustomTag");
    }
    }
  3. Finally, rebuild your solution. You should now be able to use your custom tag in a view.
    [% myCustomTag 'arg1' %]
Do you find this information helpful? Please log in to provide feedback.

Last updated: Dec 11, 2020

Recommended reading