While working on my series about all the places you can put your code in a Dynamics 365 Portals implementation, I ran into an odd quirk with regards to how Liquid is handled in the Custom JavaScript attribute of Entity Lists. I did a bit of digging, and was able to figure out why in some instances, Liquid code is evaluated as you’d expect, and in other cases, it is not.

The Custom JavaScript attribute on the Entity List entity is a very useful tool – it allows you to include arbitrary JavaScript to customize the Entity List to do almost anything you need. It appears on a number of different entities as well, including Web Page, Entity Forms, and Web Form Steps, all for the same purpose. One great feature about this attribute is that (in most cases at least), in addition to JavaScript, you can also include Liquid markup. However, I recently discovered that is some cases, Liquid markup is ignored when included in the Custom JavaScript attribute for Entity Lists.

Liquid markup is a server-side language originally developed for the Shopify platform. It’s a fairly basic templating language, meant for handling logic like if then statements and loops. But, even though it’s pretty simple, it enables us to do some really cool things with Dynamics 365 Portals.

Where I First Noticed A Problem

I was working on a Partner Portal implementation and I tried adding some Liquid markup to the Entity List that a user sees on the Support page – it’s an Entity List of their active support cases called Customer Service – Cases List. I had copied some code from another project that I knew was functional, and yet it didn’t seem to work. Upon further inspection, I noticed that I could see my Liquid syntax in the source of the webpage – which is strange because normally Liquid markup is evaluated on the server, and all you see in the page markup is the results of the Liquid logic, not the original code.

I knew that we’ve used Liquid within the Custom JavaScript attribute many times, and as a sanity check I found another instance where we did that, so I proceeded to compare the differences between the two scenarios.

Entity List: Included via Liquid or via Server Control?

I quickly identified the difference between when it worked and didn’t work: it depended on how the Entity List was included on the page.

There are essentially two ways to include an entity list on a page: using Liquid tags, or using Page Templates that use the older-style ASPX Rewrites.

When using the Rewrite Page Templates, Entity Forms, Entity Lists and Web Forms are included on the templates using ASP.NET Web Controls. These web controls find the Entity Form, Entity List, or Web Form related to the current page, and perform all the work of rendering them. As long as the Page Template you choose has these controls on them, the Entity Form, Entity List or Web Form will show up automatically, and the Liquid markup will be evaluated.

If you are using the newer technique of defining Page Templates using Web Templates, you can include these elements using Liquid. There are Liquid tags that help you out with Entity Forms and Web Forms, and there is a built-in template that helps you out with Entity Lists. It’s this built-in template that is the source of our issue.

The Built-in Entity List Liquid Template

To use the built-in Entity List liquid template, you can use the following line of code:

{% include 'entity_list' key:page.adx_entitylist.id %}

If you’re interested, you can download the Portal Source from here, or you can check out the Liquid file in question at the xRM Portal Community Edition on GitHub here.

When you look at that file, you notice near the bottom that the adx_registerstartupscript attribute is place on the page, but any Liquid code that it might contain is not processed.

On the other hand, if you look at the source code for the web control, available here, you’ll see around line 293 that any Liquid markup in the contents of the adx_registerstartupscript attribute are processed.

Why Do Entity Forms and Web Forms Work Either Way?

When I discovered this, I first thought that perhaps the limitation was with including any of these items using Liquid, including Entity Forms and Web Forms. But a quick test revealed that when you include Entity Forms or Web Forms using Liquid, any Liquid markup within the Custom JavaScript attribute is processed. What’s the difference?

It turns out that the implementation of the Liquid tag for Entity Forms and Web Forms leverages the web controls. In fact, if you look in the code here, you’ll see that the Liquid tag simply puts in a placeholder HTML comment, which is processed later on during the render by this code, which replaces the comment with the appropriate web control.

So, in the end, the Entity List Liquid implementation is done in pure Liquid, but doesn’t include processing the Custom JavaScript attribute for any Liquid it might contain. So if you need Liquid within Entity Lists, use a Rewrite-type Page Template and you should be fine.