Dynamics 365 Portal: How Does the Entity Form or Entity List Get on the Page?

A topic I find that often leads to confusion for those new to Dynamics 365 Portal development (and even for those who have been doing it for a while) is the various options for displaying an Entity List or an Entity Form on a page. So in this week’s post, let’s look at the options.

I typically will start off with a quick intro on the topic I’m discussing – this time it is Entity Lists and Entity Forms. However, this is more of an advanced topic, so if you’re not already familiar with them, it’s probably not going to mean a whole lot to you. See this link to find out more about Entity Forms, and this link to find out more about Entity Lists. At a super high level, these technologies allow you to expose Dynamics 365 Forms and Views to your portal users.

Let’s assume you’ve already configured your Entity List or your Entity Form. How do you go about making it actually show up on your portal? The options we’ll talk about include:

• Using specific Rewrite type Page Template with the out-of-the-box Entity Form and Entity List relationships on the Web Page record
• Using the Liquid entityform and entitylist tags
• Including the entity_list Liquid template (note that this option doesn’t exist for Entity Forms)

The thing to always keep in mind is that Entity Lists and Entity Forms don’t magically appear on the page – they are there because the Page Template has included them, or they’ve been included as part of the Web Page content. Since many of the out-of-the-box Page Templates include them, it may appear as if you just need to set the relationship on the Web Page, however if your Page Template or Page Content don’t specifically leverage the relationship, they won’t show up.

Using a Rewrite Page Template and the Out-of-the-box Relationships

The traditional way to add an Entity List or Entity Form to a page to set the Entity List or Entity Form lookup field on the Web Page, and then to use a Rewrite-type Page Template that has the <adx:EntityForm> and <adx:EntityList> ASP.NET tags included on it.

(For those of you who have only used the Microsoft version of the Dynamics 365 Portal product, and have never dug through the Portal source code, that last sentence may not have made a whole lot of sense. Hopefully it made a bit of sense to those with Adxstudio v7 experience.)

So in general, this technique is pretty straight forward, but unfortunately there is no easy way to know if a Rewrite Page Template contains those tags. The good news is, most do. Most Rewrite Page Templates have a specific purpose, so you’re probably not using them beyond their intended purposes, but of the more generic page templates (Full Width, Page, Web Form, Listing and Blank), Blank is the only one where it doesn’t contain those tags.

Using the entityform and entitylist Liquid Tags

If you’re using Web Template Page Templates, then you have a different option: using the entityform and entitylist Liquid tags. These can be included in the Web Template used as the Page Template, or even directly in the Web Page content itself.

entityform Liquid Tag

The entityform Liquid tag is pretty straight forward:

{% entityform name: 'My Entity Form' %}

or

{% entityform id: page.adx_entityform.id %}

Notice how we have to pass the name or ID of the Entity Form in the Liquid tag – that goes back to my note above about there being no magic. You could invent your own way to determine which Entity Form to display (perhaps via a FetchXML query). The tag does not automatically pull the ID from the out-of-the-box relationship.

It’s important to note that you can only have one of these per page – any subsequent uses of the entityform Liquid tag after the first one will be ignored. However, you can leverage IFrames so that it looks like there are multiple forms on a page (that’s how it works when you get dialogs for creating new records or editing existing records within an Entity List).

The other important thing to know is that this Liquid tag actually just calls the exact same code that the <adx:EntityForm> code uses. So whether you use Liquid or the Rewrite Page Templates, you’ll get the exact same result. As you’ll soon see, that is not the case with Entity Lists.

entitylist Liquid Tag

The entitylist Liquid tag is not so straight-forward. It doesn’t provide the Entity List implementation – it simply provides the details you need to implement it yourself.

If you were forced to creating your own Entity List implementation, that would kind of defeats the purpose of using this platform – the whole point is that we can build these portals without writing a ton of code. Thankfully, Adxstudio/Microsoft provides a implementation that we can copy and paste into our environments. You can find that implementation here (for now, use this link from the old Adxstudio site – the Microsoft version is missing a bunch of quotation marks).

If you compare the results of these 217 lines of code versus the what you get if you use the Rewrite Page Template, you’ll immediately notice some differences. For example, the paging looks different, and the implementation using the Liquid tags doesn’t support Action Buttons, metadata filters, among other features. As Nick Doelman (@readyxrm) mentioned in one of his blog posts, the Liquid implementation doesn’t support the ability of turning your Entity List into a calendar or a map. This is because, while both options are referring to the same configuration, they don’t use the same code base and they differ in their implementation.

In general you can think of the Rewrite Page Template version to be the fully-featured version, but the Liquid version is more customizable, and makes it possible to include multiple Entity Lists on a single page.

Note that you can use the entitylist liquid tag on a page using a Rewrite Page Template if you want, but you cannot use the entityform tag on a page using a Rewrite Page Template.

Including the entity_list Liquid Template

There are a number of built-in Web Templates that are a part of the Portal website code that you can reference, but you won’t see them listed in Dynamics under Web Templates (see this page for a listing). While it’s not documented in that list, there is one called entity_list that you can use to render an Entity List:

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

This approach is somewhere in the middle between the two other options – it more closely resembles the Rewrite Page Template option (includes support for Action Buttons, for example), but doesn’t support things like the calendar or map views.

If you look at the source code, you’ll see that it uses the entitylist Liquid tag, but it also uses some of the framework used by the <adx:EntityList> web control to display the table. This explains why the tables for each implementation look the same, and they both support action buttons, but also why the Liquid template doesn’t support the calendar or map views, as the functionality hasn’t be built into that Liquid template.

I tend to prefer the entity_list Liquid template over the entitylist Liquid tag, as there is less copy-and-pasting, and less code to maintain. I also prefer to have the consistency between all of the Entity Lists that appear on a portal.

Custom JavaScript, and Liquid in Custom JavaScript Inconsistencies

I covered this in a previous blog post, but I think it’s worth recapping one other difference between some of the options, and that’s support for Liquid in the Custom JavaScript attribute, and the Custom JavaScript attribute in general:

• The Rewrite Page Template options support including Liquid in the Custom JavaScript attribute for both Entity List and Entity Forms
• The entityform Liquid tag supports Liquid in the Custom JavaScript attribute, because it is using the same code base as the Rewrite Page Template
• The Microsoft-provided implementation using the entitylist Liquid tags does not output the Custom JavaScript attribute at all, but it would be possible to add that support yourself
• The entity_list Liquid template supports the Custom JavaScript attribute, but any Liquid code does not get evaluated

Keep these differences in mind when choosing which option would work best for your situation.

The post Dynamics 365 Portal: How Does the Entity Form or Entity List Get on the Page? appeared first on Engineered Code.