Inline Instructions with Power Apps Portals – Part 1

I’ve worked on Power Apps Portals over the last few years and a common requirement involves adding inline instructions within Entity or Web Forms. Fortunately, Power Apps Portals offers some out of the box for tools for managing labels and extended content:

• Attribute label: The CDS Entity Attribute label is the default used by the Portal when rendering forms. We can update the Attribute label or the CDS form reference and it will be rendered on the Portal. One big limitation with this method is the length limit of 50 characters
• Section label: As with the Attribute label, we can include additional instructions for an entire Section. This Section label has much longer Attribute length and we can include simple formatting HTML in the Section Name that the Portal will render
• Web and Entity Form Instructions: Portals supports form level instructions using the Instructions Attribute for Entity Forms or Web Form Steps. This Attribute actually accepts Liquid, so you can render dynamic content if needed
• Metadata: We can override labels for Tabs, Sections, and Attributes using Entity and Web Form Metadata. This is a common method for bypassing the Attribute label length restriction which also allows for some simple formatting HTML

These options work well for most situations but one concern may be content management. Below is an updated Contact Us Entity Form for the Lead Entity demonstrating several of these options:

In the image, we can see:

1. Instructions Attribute
2. CDS Form Section label
3. Attribute Entity Form Metadata Label
4. Attribute Entity Form Metadata Descriptions / Instructions
5. CDS Form Attribute Label

Each method above requires some level of administrative access to the Portal configuration or solution customizations. Your customer may require that a non-developer or non-administrator to manage this content which can be a risk. What if this person inadvertently breaks something on the portal? Cost may be an issue too. If content is managed in the customizations, this may mean assigning a license to one or more new users.

We had this requirement on a recent Power Apps Portal project built to accept complex online applications. The applications originated from fillable PDF forms with many pages of complex instructions. We converted them to a “wizard style” Portal interface which meant moving the instructions inline on our forms. The instructions included formatted content and some conditional display rules. Most importantly, their administrative team needed access to manage this content because it could can change frequently.

These combined requirements forced myself and my teammate to design an alternative solution for managing and rendering extended instructions within our Portals forms.

Defining custom instructions

The initial design focused on extending Attribute level instructions but we quickly saw a need for additional context at the Page, Tab, and Section levels. We also quickly realized that we would need to store and render HTML, such as lists, simple styling, hyperlinks, or images.

These two requirements meant defining context for our instructions and a place to store the HTML based content – what content should be displayed and where on the Form should it be rendered?

Context and Filtering

First, we created a custom Entity in CDS named Instruction Map. This Entity captures scope and target details such as the Tab, Section, Attribute name where and how content will be displayed, such as inline or as a modal dialog.

With the Attribute, we had some situations that included conditional display of instructions. For example, if they choose Yes to a particular Attribute, display some additional instructions. We added some Attributes for simple rules for “triggering” display so that we have one one place to manage this logic.

The Instruction Map Entity also includes some filtering details for when we want to retrieve a batch of content rather than retrieving all records or naming individual items. Our first set of filtering Attributes included Web Form Step or Entity Form names. This allowed grabbing all content for a specific Portal form. If you want to reuse Instruction Map records, a single Entity Form or Web Form Step would be too specific. So we added another Attribute named Filter Group for a more generic method of filtering. Filtering Instruction Map records for retrieval is an area that has some room for flexibility and we will see more when we look at rendering.

HTML Content

Because non-developers need to administer Instruction Map records, we felt the need to include a visual editor for the HTML content. Adding an editor to a CDS form and saving HTML content is a fairly common ask, and with PCF controls, it’s much easier to implement! Check out some of the Rich Text editors at the PCF Gallery by Guido Preite for some very cool examples. Fortunately, the existing Power Apps Portals Content Snippet Entity already supports this capability. So we decided to simply add a relationship to the Content Snippet Entity on our Instruction Map Entity.

The added benefit of using the Content Snippet Entity is Liquid Templates support, meaning Liquid added to the Content Snippet body will render. This provides the ability to make instructions even more dynamic if needed. For example, we can build a single Content Snippet aware of the page in which it’s being loaded and load different content depending on the parent page. Additionally, the Content Snippet Entity already supports Languages – you can provide translations for your Instruction Map content as you would other content in your Portal.

Next steps…

We created have a custom Instruction Map CDS Entity to define a context for display of custom content on a Portal Form, store the related HTML content, and detail simple conditional display rules. Below we list the key Attributes for the new Entity:

• Instruction Scope – OptionSet indicating the location of the content: Page, Tab, Section, or Attribute
• Display Mode – OptionSet indicating how the content should be displayed: Modal, Tool Tip, Inline, Inline Conditional, Label
• Content Snippet – Lookup to the Content Snippet
• Filter Group – Optional general tag for filtering on retrieve of the Instruction Map records
• Web Form Step Name – Optional Web Form Step name to which this content is associated
• Entity Form Name – Optional Entity Form name to which this content is associated
• Tab Name – Optional Tab name where the content should be displayed, as defined in the CDS Form
• Section Name – Optional Section name where the content should be displayed, as defined in the CDS Form
• Attribute Schema Name – Optional Attribute schema name for this content, as defined in the CDS Entity Metadata
• Attribute Display Type – Optional OptionSet indicating what type of input is being used for the Attribute used to determine the conditional triggers
• Attribute Conditional Value – Optional text value of the Attribute that will cause the conditional display of the content
• Instruction Title – Optional text that will be displayed in the Modal header
• Link Text – Optional text that will be displayed on the link for a Modal option

Now that we have a place to define our content and describe where and how it should be rendered, how do we actually use this information to render additional content in our Portal Forms?

In Part 2 of this series, we will dive into the Liquid Templates and scripts that render our new Instruction Maps, including associating content with specific forms and how to render the saved HTML dynamically (that part was tricky). The next post will include an update to the shared Portal Scripts repository and a new Portal to demonstrate live examples of inline instruction and content.

Until then, comments and questions are all welcome!