Use DotLiquid to create custom tags

14 min

Important

Classic CMS reached end-of-life in January 2025 and is no longer receiving feature updates or bug fixes. You should [migrate to Spire CMS](../../End user docs/spire-cms/get-started-with-spire-cms/migrate-from-classic-cms-to-spire-cms.mdx).

DotLiquid is an HTML templating engine used in Configured Commerce website views. Additional info can be found on DotLiquid.

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

Configured Commerce DotLiquid tags

Configured Commerce 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. 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.

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 will need to create your startup file in the extensions project.

namespace Extensions.StartupTasks
{
 [BootStrapperOrder(101)]
 public class RegisterCustomDotLiquidTags : IStartupTask
 {
     public void Run(IAppBuilder app, HttpConfiguration config)
     {
         Template.RegisterTag<MyCustomTagType>("MyCustomTagName");
     }
 }
}

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

[% myCustomTag 'arg1' %]