ENGINEERED CODE BLOG

Dynamics 365 Portal: Using Liquid to Create Conditional Entity Forms

During last week’s eXtreme365 event in Austin, Texas, I was lucky enough to co-present a session with Nikita Polyakov (a Senior R&D Solution Architect at Microsoft, with a focus on Dynamics 365 Portal implementations). One of the tips he mentioned during the session was about using Liquid to decide which Entity Form to display on a page – it’s a very cool technique that seems to be underused. Then, a question showed up on the Dynamics 365 Community forums where that technique could be used to solve the problem. So I figured I’d write a quick blog post to get the word out on using Liquid to determine which Entity Form to display on a page.

Entity Forms – A Very Brief Intro

Entity Forms are a foundational concept in the Dynamics 365 Portal product, and combined with Entity View and Entity Permission, create a platform that makes it possible to develop relatively complex applications quickly. At a very high level, Entity Forms allow you to expose a CRM form on your portal, with support for creating records, viewing records, and updating.

The traditional way to include an Entity Form on a Web Page is to use the Entity Form lookup. Most out-of-the-box Page Templates will render the Entity Form just below the main content of the page. This means that there is typically a single Entity Form per Web Page. However, if you implement your own Page Template using a Web Template, through the power of Liquid you are able to get more control.

Entity Form Liquid Tag

The entityform Liquid tag gives you the ability to put the Entity Form where you want it. There are a few things to note:

  1. It can only be used on pages that leverage Web Template-based Page Templates (see our YouTube video for a comparison of the template types).
  2. You can specify the Entity Form by using either the name or id parameters.
  3. It can only be used to render a single Entity Form per page. Any tags encountered after the first one is rendered are ignored.

Common usages include:

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

This option uses the out-of-the-box Entity Form lookup field on the Web Page entity to set the id parameter of the Liquid tag to the Entity Form related to current Web Page.

{% entityform name: 'Contact Us' %}

This option allows you to include an Entity Form by name.

Conditional Logic

The original poster on the inspirational Dynamics 365 Community forum thread wanted to show either an editable Entity Form or a read-only Entity Form, depending on the value of an option set. This can be achieved by setting up two different Entity Forms (one read-only, and one editable), and using the following Liquid to choose between those two:

{% assign id = request.params['id'] %}
{% assign primaryentity = entities.new_customentity[id] %}
{% if primaryentity.new_optionset.value == 100000001 %}
    {% entityform name: 'Editable Entity Form' %}
{% else %}
    {% entityform name: 'Readonly Entity Form' %}
{% endif %}

The first step is to get the record so we can determine the value of the option set field. This example assumes the ID of the entity is in the id query string parameter, as it is in many cases.

Next, we have a simple if statement that checks the value of that field, and renders two different Entity Forms, depending on the value. In this case, we’re assuming the Entity Forms have the names of Editable Entity Form and Readonly Entity Form. As I mentioned above, you can only render one Entity Form Liquid tag per page; however, due to the if statement, only one will ever be processed.

A few things to note:

  1. The field we use to determine if it is editable or read-only does not need to appear on the form, since the Liquid runs server-side and is independent of the form.
  2. If you choose the Display Success Message option for the On Success field, and you uncheck Hide Form on Success, and you change the value from the editable to the non-editable value, the editable version of the form will be displayed after saving. This is because the code does not rerun the Liquid logic after a form post back. You should use either the redirect option, or hide the form after save.

While there are other techniques you can use to provide different Entity Forms based on a particular value (such as by setting up different pages with a single Entity Form on each, and then use JavaScript to modify the URL the user clicks on to get to that page), I think this technique is a lot cleaner as the end user only sees one web page URL.

12 responses to “Dynamics 365 Portal: Using Liquid to Create Conditional Entity Forms”

  1. […] post Dynamics 365 Portal: Using Liquid to Create Conditional Entity Forms appeared first on Engineered […]

  2. […] actually covered this topic just a few weeks ago, so I’ll just cover this technique at a high […]

  3. Ovidiu says:

    “It can only be used to render a single Entity Form per page. Any tags encountered after the first one is rendered are ignored.”

    is this still valid for portals online in 2020 ? I’ve just test it and it renders multiple entityforms in the same page

  4. Chris says:

    Excuse my naivety, how do I reference this from the page javascript?

    I want to click on an image on the page, and for the related entity form to load.

    If I’ve understood correctly I need to put this line in the web template:

    {% entityform name: ‘Contact Us’ %} (with the name of the form I want)

    What do I then do in the javascript?

    Many thanks

    • Nicholas Hayduk says:

      Hey Chris,

      Liquid code runs on the server, so you can’t use JavaScript to make it “load” unless you start getting into techniques like IFRAMEs.

      Can you provide me a bit more details on what you’re trying to achieve?

      Nick

  5. Mohammed Fakhri says:

    Can we have a simple if statement that checks the value of field or a Web Role, and renders two different Entity List, depending on the value ? In this case, we’re assuming the Entity Lists have different names as well.

  6. Mohammed Fakhri says:

    This actually doesnt work. I have tried this however there is a workaround. For anyone who is looking for it.
    1. Create a webtemplate and include reference to a Entity List.
    2. Use WebTemplates instead of a EntityList in the if else condition similar to your solution.

  7. Jharana says:

    Hi All,

    Retrievinf data & show in portal using liquid is possible but is it possible record creation & updation in liquid template in portal CRM ? I mean data save using liquid ?

    Thanks
    Jharana

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.