Now that we have a general understanding of the structure and purpose of Entity Forms, what are some of the other features? What options are available for the form itself? What control do we have? What should we avoid? Can we point the Entity Form to another or to another external website?
Part A covered some essential background knowledge of Entity Forms, the General tab of the Entity Form record, and the Web Page.
Part B, this blog, will cover the Form Options and On Success Settings tabs on the Entity Form record.
Part C will cover the Additional Settings, Entity Reference, and Entity Form Metadata tabs on the Entity Form record.
As a disclaimer, I will not cover every field or scenario for Entity Forms, however, I am placing emphasis on items that may be confusing or have more value than others.
The Form Options tab on the Entity Form record has exactly that – options. It provides options to add a layer of security, to easily make all fields required or to show each form tab as a step, and to append to the outgoing URL after the form has been successfully completed.
You have the ability to add security to your Portal website by including Captcha features, and it is super easy to implement.
Navigate to the appropriate Entity Form and Form Options tab. Check the Add Captcha box, save, and clear portal cache.
When the Web Page is refreshed, the Captcha component will appear and function appropriately for either authenticated or anonymous users. If you only want to add this for authenticated users, check the Show Captcha for Authenticated Users.
If the Captcha is not filled out correctly, the user will not be able to submit the form.
Here is Microsoft’s definition of this field:
After developing the Application form, I realize I need to make Application Type a required field from the Dynamics 365 Sales side. By doing this, it will automatically make it a required field on the Portal.
Forcing the field to be required in Dynamics 365 Sales:
Portal automatically makes it required.
But now, a new requirement surfaces in that Sponsor needs to be required, but only on the Portal side of things. How do we accomplish this? You can use Entity Form Metadata to make the field required versus optional. But what should you do if you need specific validation outside of the field just being populated?
This is a scenario where Validation Group comes into play.
Navigate to the desired Entity Form, and enter a meaningful name for Validation Group on the Form Options tab.
Once the Portal is refreshed and you view the source code, you will see some interesting things.
HTML of Validation Summary DIV
This is an HTML DIV tag that is automatically generated when the page loads that holds the error messages that will be displayed to the Portal Users. It looks something like this:
HTML of Application Type Field
The code above provides the container for the Application Type field, and the result of this code looks like this:
In general, the code above builds out the necessary form validation for each specified field. In particular, the code does the following:
- Line 6-8 assigns a default error message to the variable.
- Line 9 assigns the Validation Summary <div> to the AppGroup of which we defined in the Entity Form.
- Line 16-20 assigns a default error message to the variable for the Application Type field.
Using Arpit Shrivastava’s example, we can make the Sponsor field a required field and add any other data validation requirements if needed.
I know this section was quite detailed, but it gives you, hopefully, a better understanding of the purpose of Validation Group and how it can be consumed.
Auto Generate Steps from Tabs
We can spread out a large form across multiple steps using the Auto Generate Steps from Tabs. Try to get a better understanding of your clientele before you create Entity Forms or Web Forms. Some of the choices are: 1) large but few steps or 2) small but many steps.
From our previous Application form, we decide to add another tab to allow the Portal user to enter why they want to apply.
With Auto Generate Steps from Tabs unchecked, the new Portal form would look like this:
On the Portal, the Reason field is on the same “page” as that of the general information. Our preference is to have the Reason field all on its own, so we check the Auto Generate Steps From Tabs field:
Save, clear Portal cache, and refresh the Portal page.
Instead of the Submit button down at the bottom, we now have a Next button.
When clicking Next, we see this as the next step:
The Reason field has become its own step, and now, there is a Previous and Submit down at the bottom.
Render Web Resources Inline
Inside Dynamics 365 Sales and their forms, separate containers of HTML can be added to increase value and functionality to the user. These same containers can be pushed out to the Portal Entity Forms.
Here is the Dynamics 365 Sales form editor for the Portal Application form.
When displayed out to the Portal, it would look something like this:
The HTML code looks like this:
The HTML Web Resource is placed inside an iframe in the HTML code. And depending on what you are attempting to achieve, an iframe can cause difficulties for either developers or your users.
When we check the Render Web Resources Inline, the display will look similar, like this:
You will notice the iframe border is removed and only the field border remains.
The code will look like this:
The iframe tag is replaced with a custom literal tag.
Most likely you will not need to check this, but in case you have special circumstances on your Portal, now you know what it does and how it operates.
Enable Validation Summary Links
The default value for this field is checked.
That means when a user experiences an error in the Portal for an Entity Form, the field-specific error is converted into a link.
Clicking on the link will shift focus to the field in question; it is merely a feature to aid the user in finding the correct field.
With the field unchecked, we will see the below Portal error message instead:
Validation Summary CSS Class
If special or additional CSS styling is needed for the error messaging, you can enter a CSS class value for the Validation Summary CSS Class field and then provide your own styling on the Validation Summary HTML element.
After the Portal is refreshed and an error is purposefully generated, you can view the HTML code, and it will contain something like this:
From here, you can add CSS styling to your CSS Web File(s) or to the Advanced tab of the containing Web Page. For display purposes, I will demonstrate the latter.
Adding CSS to the Portal Application Content Page Web Page (Not the Information Web Page):
Testing error with added CSS:
As the PowerApps Portals utilizes Bootstrap CSS, most likely several layers of CSS will need to be added to override or complement it.
Several times it is necessary to provide users useful instructions on what information they need to fill out the form successfully or what steps to follow after the form is submitted. By filling out the HTML-supported Instructions section on the Form Options tab on the Entity Form, you can do that.
Display of instructions on Portal form:
There are no options of where to display the instructions; they automatically are placed on top of the form.
On Success Settings
What should happen when the user successfully completes the Portal form? The On Success Settings tab on the Entity Form record provides two options: Display Success Message and Redirect.
Display Success Message
Here are the default settings for the On Success Settings tab:
When the form is successfully completed, the form is hidden, and a default successful message is displayed:
The URL remains the same, meaning that the user did not navigate to a different page. You may notice in the image above that the form instructions are still visible. This may be confusing for the user as they may expect to be redirected to another page, view different instructions, or maybe redirected back to a previous starting point. These are several good reasons to have the redirect option.
For a redirect, we have many more choices that essentially will send the user somewhere else, bringing along some key information if needed.
We can redirect to an external website (External URL) or to another Portal Web Page (Web Page).
Adding an External URL would look like this:
Regardless of which option is followed, we can add parameters to the URL.
By checking Append Existing Query String, we would be redirected to the following:
By checking Append Record ID To Query String, we would be redirected to the following:
We can enter a legitimate name/value pair in the Append Custom Query String like this:
We would be redirected to the following:
We can even add a parameter and value from one of the fields of the specified (target) entity. We would add the following information like this:
The logical name matches the name of the field in the solution:
When completing the form successfully, we would be redirected like this:
This last option has limitations, so use wisely. For example, if a customer or lookup field is added, only the GUID value would be represented in the URL.
This blog has explored some of the main features of the Form Options tab on the Entity Form. By all means, spin up a trial Dynamics 365 instance and Portal and trial and error your way through a greater understanding. In the next blog, we will delve into Additional Settings, Entity Reference, and the Entity Form Metadata.
If you have any questions about using Power Apps Portal, please get in touch with us.
Which Dynamics Product Is Best for You?
Answer some basic questions about your company and your requirements, and find out what products would fit your business.Take Our Quiz