Liquid Templates in Dynamics Portals – Part 1

I’ve been working on Dynamics Portals projects over the last few years.  My first project involved heavy use of Web Forms and Web Form Steps and customizing forms using JavaScript. On my current project, I’ve had the opportunity to dive into Liquid Templates.

In this series of posts, I hope shed some light on one question that I had when first diving into Portals: What the heck are Liquid Templates and how can we use them in Portals?

Some Portals background

The documentation for Portals on docs.microsoft.com is pretty solid and includes a good definition Liquid Templates with regards to Portals:

Liquid is an open-source template language integrated into portals. It can be used to add dynamic content to pages, and to create a wide variety of custom templates.

“Work with Liquid templates”

Liquid Template support allows developers to customize their Portal past standard record based configuration. This includes customizing Portal page design and layout, adding custom data elements, or changing the logical flow of a Portals based application.

Liquid Template code executes on the server. This means that your template logic will run before the page is ever rendered, giving developers access to powerful capabilities not available via client side scripting.

Liquid Templates support has been available in Portals for some time. Adxstudios was acquired by Microsoft and the their Portals product has been re-branded into Dynamics Portals. While changes have been made to the platform in the few years since the acquisition, much of the functionality remains the same, including the Liquid Templates support.

When the support for Adxstudios Portals ended, we saw the release of Adoxio xRM Portals Community Edition:

Microsoft has released the Portals Source Code to the Microsoft Download Center under MIT license for developers to download.

“xRM PORTALS COMMUNITY EDITION”

So now you can download a copy of the community version of xRM Portals and host in your own environment. This also allows developers a bit of insight into how the Portals solution works.

Open Source?

The Microsoft documentation does not provide much background on the Open Source template language being used by Portals. We could dive right in and start using Liquid Templates in our Portal, but I like to have some background as I learn something new. Specifically, I am looking for a better understanding on core features and what extensions have been added by Microsoft.

Now that we have the Community Edition code, we can take a peek under the hood. In the solution, we see a reference to the DotLiquid NuGet package. This project is a .NET port of the original Ruby based Liquid Template language created by Shopify. As their site notes, this templating language has been around since 2006 and it’s been proven by its use by many companies on a variety of products.

These additional sites provide some documentation as we start digging into Liquid Templates. While solid, the documentation provided by Microsoft is not complete, focusing on their Liquid Template extensions and Portals specific examples.

Portal building blocks!

Back to the note from the Microsoft documentation. What do they mean by “integrated into portals”? First, we can take a step back and look at the overall Dynamics Portals solution.

I like to view Portals as a content management system hosted on the Power Platform. Of course, Portals offers more than simple content management, such as exposing data from and collecting data for Power Apps like Dynamics 365 CE. When installing Portals in a new environment, we can install fully functioning solutions, such as a Customer Self-Service Portal that offers access to Knowledge base articles, trouble ticket submission and management, etc. You can see a quick breakdown of the pre-built Portal features at the Provision a Portal article. Pretty powerful stuff!

We can configure our Portal by creating or editing Entity records related to Portal components, such as Website, Web Pages, site navigation, Entity, Lists, and Entity forms.

This is all standard Portals work… How does this relate to Liquid Templates?

Well, the Microsoft Portals development team uses Liquid Templates when building the out of the box Portals. Looking at the Customer Self-Service Portal, we can see an example of Liquid Templates right in the Home page. Looking at the Web Page record, we can open the Page Template named Home, and see that it is configured to use a Web Template, also named Home.

All configuration records so far.

But once we open up the Home Web Template record and view the Source attribute, we can see Liquid Templates in action.

In the source, the first bit we see are some curly braces with an ‘assign’ keyword, followed by some HTML and then a few more curly braces and keywords. So what are we looking at in the source?

Liquid Templates Markup

Liquid is a templating language which means that we provide an overall output template mixed with Liquid tags that the templating engine can process. For developers, should be somewhat familiar. It actually reminds me a bit of the Razor syntax used by ASP.NET MVC Views. If you are not a developer, the curly braces enclose our Liquid code allowing the Liquid Template engine to separate it from the rest of the static HTML.

With Liquid Templates, we can work with data as objects and object collections, conditionals such as if/then, and programmatic flow with for loops. In the Home page example, we can see the assignment of a value in the very first line:

{% assign forums_sm = sitemarkers["Forums"] %} 

This one line is pulling a value out of the sitemarkers object collection and assigning it to a value to be used later in the template. Also in the template, we can see the following line:

{% include 'Search' %}

This simple statement is using another template named Search within the Home page. This seems pretty small but it’s a great example of code reuse offered up by the Liquid Template engine. Microsoft built their Search template code once and they can reuse it as needed. In this case, the Search Liquid Template is a 60+ line Liquid Template that can be reused with a single line of code!

Digging deeper

So this is a pretty high level overview with a simple example that only just scratches the surface of the Liquid Templates capabilities. For example, how can I loop on data returned from the Portal? What if I want to render something that is not HTML? What if I have some conditional logic that I need to check?

In the next few posts, we are going to dive into the core Liquid Template functionality and cover some of the Portals specific extensions available with Dynamics Portals. We are also going to look at some real world examples of using Liquid Templates in Portals.

In the meantime, questions and comments are all welcome!