Skip to content

Dynamics 365 Portal: Using Liquid to Create Conditional Entity Forms

Nicholas Hayduk December 10, 2018 3 Min.To Read

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.

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.

Leave a Reply

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

14 responses to "Dynamics 365 Portal: Using Liquid to Create Conditional Entity Forms"

Back to top