Message template tokens (DotLiquid)

*More information about DotLiquid can be found at this link.


General information

DotLiquid in GrandNode was introduced in order to replace what previously was called message tokens. It gives developers/store administrators more freedom in customizing message templates, allowing to write C#-ish code in message template body. Starting from GrandNode 4.40, instead of using ITokenizer for replacing tokens in messages' subject and body, they will be rendered by DotLiquid. Lets analyze how OrderPlaced.CustomerNotification is sent to better understand how everything works.

In line 548 LiquidObject is instantiated. It is an object that acumulates all DotLiquid Drops, like LiquidOrder, LiquidCustomer etc. Only those classes (DotLiquid Drops) can be used in rendering message subject/body, because they inherit from Drop (reason for that you can find in original documentation):

Adding Tokens via IMessageTokenProvider is nothing more than setting LiquidObjects' property to appropriate object created based on passed data, so for instance adding order tokens sets LiquidOrder property in LiquidObject to newly created LiquidObject Drop.

After all required tokens are added (all Drops we might need are set) SendNotification method sends an email, replacing tokens in messages' subject and body with appropriate values beforehand: 


Creating message templates

It is best to learn based on example, so we advise to study OrderPlaced.CustomerNotification which is a great sample of how to use Drops as well as conditional clauses and loops. Generally speaking, the rules are as follows:

 - Use {{Property}} for properties that are contained directly by LiquidObject

 - Use {{Object.Property}} for properties that belong to specific object, for example {{Order.CustomerFullName}}

 - Use {% if Boolean %} and {% endif %} for conditional clause

 - Use {% for item in Order.GiftCards -%} and {% endfor -%} for loops, "-" will suppress the line break that would normally follow the end of a tag


Adding additional tokens

If, for whatever reason, you need to add your own tokens, you can do so utilizing AdditionalTokens property of both LiquidObject and each of the Drops. One way of doing it is to create EventConsumer, ideally in your own plugin if you don't want to change source codes:

It gets triggered before message template containing Order tokens is being rendered and adds them to the dictionary, allowing you to "call" your tokens in message tamplates' body like this:

{{Order.AdditionalTokens.Key1}} //will render "Value 1"

{{AdditionalTokens.Key2}} //will render "Value 2"

back to top