Engineered Code is proud to announce the availability of ecLearn - the Learning Management System built on top of Microsoft Dataverse

ENGINEERED CODE BLOG

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.

22 responses to “Dynamics 365 Portal: How Does the Entity Form or Entity List Get on the Page?”

  1. Rohan says:

    Wooo !!! Hey Man, how can I thank you ? I am beginner learner in portal world and you are always there with exact solutions of very specific doubts I have.

    Thank You so much Buddy!!!

  2. Ravi Kashyap says:

    Hi Nicholas,

    Do you know if you can use entityform tag to open an entity form set to readonly for a specifc record?

    • Nicholas Hayduk says:

      Hi Ravi,

      The Liquid tag doesn’t accept parameters for the mode and the ID of the record (as far as I know). The tag should respect the mode of the Entity Form, so if you set it to read-only, that’s what you should see. To show a specific record, I believe you’ll have to use the query string.

      Nick

  3. Raj says:

    Hey Nick, Is there a way to completely customize/style the form instead of using this tag? I want to rewrite my own form and submit to CRM entity but not able to find a solution for that. Thanks.

    • Nicholas Hayduk says:

      You’re options today are trying to modify the markup using JavaScript, or to build the form yourself and use a Companion App to save the data to the server. Soon we’ll have the WebAPI for Portals (preview I think is scheduled for July), which means you can build your own form and save the data to the server by calling that API.

      Nick

  4. Nandhini says:

    Hi Nick,
    I have added two entity forms in a webtemplate and both the entity forms having the field called ‘Telephone’ & ‘Email’.

    {% entityform name: ‘EF_Account’ %}
    {% entityform name: ‘EF_Contact’ %}

    On load of the web-page, I’m getting the error “An entry with the same key already exists.” due to the duplicate attribute name.

    Do you have any solution to resolve this issue?

    Thanks ,
    Nandhini M

  5. Rahul says:

    Hi,How can I get my form to work in both insert and read only mode?

    • Nicholas Hayduk says:

      You’ll need to setup two different Entity Forms – a single Entity Form can’t be both insert and read only.

      They can both point at the same model-drive form, but you’ll still need two separate Entity Form records.

      Nick

  6. Umer Javed says:

    Hi Nicholas,

    i am trying to set the lookup field value on entity form when Create button is clicked from Entity list page.

    I am using FetchXML and Liquid tags in custom javascript seciton of entity form however it doesn’t seem to work.
    although The fetchxml and Liquid seem to work when adding the code to a web template therefore using on a web page.

    any idea why it wouldn’t work on entityform? I have got following code.

    $(document).ready(function()
    {
    ‘{% fetchxml get_resource_query %}’

    “”+
    ” “+
    ” “+
    ” “+
    ” “+
    ” “+
    ” “+
    ” “+
    ” “+
    ” “+
    ” “+
    “”

    ‘{% endfetchxml %}’
    ‘{% assign contact_result=get_resource_query.results.entities %}’
    ‘{% for result in contact_result %}’
    $(“#ao_bookableresource_name”).val(‘{{result.name}}’);
    $(“#ao_bookableresource”).val(‘{{result.id}}’);
    $(“#ao_bookableresource_entityname”).val(‘bookableresource’);
    ‘{% endfor %}’
    });

  7. Andrew Castellano says:

    Hey, glad to see someone writing about this. Very valuable to the community.

    My Entity Form is not rendering. In my troubleshooting, I rendered page.adx_entityform.id to the screen, and it’s null…

    I have configured a value for ‘Entity Form’ on the Web Page that uses this page/web template. Is there something else I’m missing to populate page.adx_entityform.id?

    Thank you!

    • Nicholas Hayduk says:

      I’m wondering if maybe you set the Entity Form on the root page, instead of the language-specific page?

      Nick

  8. Salma says:

    Hi,
    how about webform?
    Is this right {% webform id:page.adx_webform.id %} ?

  9. Per says:

    I think I have learned more about Power Pages by reading your blog than any other resource on the internet. If we ever meet, I will definitely buy you a couple of beers.

  10. Nitish says:

    How can we pass a guid to fetch particular record from table in editable form using the above liquid tags method?

  11. sarfraz ansari says:

    How to apply the filter in the basic form i want to apply in the below scenario not getting form name in this case
    {% entityform name: ‘PM_Attachment Subgrid’ %}
    {% assign filtered_fields = form.fields | where_exp: “field”, “field.name != ‘unwanted_field'” %}

    {% for field in filtered_fields %}
    {{ field.control }}
    {% endfor %}
    {% endentityform %}

    • Nicholas Hayduk says:

      Liquid does not provide access to the individuals fields within a form. If you want to conditionally hide fields, you’re better off to use JavaScript.

      The entityform tag simply outputs the entire form. You don’t have the ability to control via Liquid what is displayed.

      Nick

Leave a Reply

Your email address will not be published. Required fields are marked *

Contact

Engineered Code is a web application development firm and Microsoft Partner specializing in web portals backed by Dynamics 365 & Power Platform. Led by a professional engineer, our team of technology experts are based in Regina, Saskatchewan, Canada.