In the previous chapter, I discussed the security aspects of Dynamics 365 portals and how to configure them. In this chapter, the main focus is on customizing the portal further to meet the requirements of the example scenario. Initially, the chapter will show how to customize the pages and add a few pages required for the application. Then, it will guide you through creating entity forms, creating entity lists, and displaying charts on your portal.
Customizing the Portal
In this section, you’ll change the text on the pages, change the banner images, and add a few new pages to meet the requirements.
Changing the Banner Text
When you log in as the system administrator, you will see the content editor; currently, there is a new editor available in preview mode. A message bar will be displayed on the top with a “Try new editor” button (Figure 3-1).
Figure 3-1
Admin login with editors enabled
First, let’s change the banner text. Just hover over the banner text and the Edit button appears (Figure 3-2). Click the Edit button and the editor window pops up. Enter the text you want to use and click Save, and the text will be changed accordingly. Similarly, change the other text on the banner. As soon as you save the changes in the respective editor, the changes will be applied to the page.
Figure 3-2
Banner text changed
Changing the Banner Image
Let’s change the banner image. In the portal app, navigate to the web files and look for the record named homehero.jpg (Figure 3-3).
Figure 3-3
Active web files, banner image
Open the record, and on the Notes tab, you will find the image that is being used. Add a new note with a new image attached (Figure 3-4).
Figure 3-4
Attaching a new image
Navigate back to the portal, and in the content editor window, select Children. Find the homehero.jpg file and click the edit icon (Figure 3-5).
Figure 3-5
Changing the banner, edit icon
The “Edit this file” window will pop up. Click the browse button, select the image from the file location, upload the file, and click the Save button at the bottom-right corner of the window. Click Save in the editor, and the browser will automatically refresh and load the page with the new image, as shown in Figure 3-6.
Figure 3-6
Portal banner after changing the banner image
Updating the Navigation
Since this portal is a custom portal, the navigation must be edited. As you can see in Figure 3-7, the out-of-the-box navigation contains a few sample pages, which we will be removing. We will add the pages we require to the navigation.
Figure 3-7
Default navigation and sample pages
To update the primary navigation, hover the mouse pointer over the primary navigation, and you will see the Edit button appear at the top of the navigation (Figure 3-8). Then the Edit Primary Navigation editor will appear, and you can add new pages, add existing pages to the navigation, remove unwanted pages, and change the position of the links.
Figure 3-8
Editing the primary navigation
Click the green add icon at the bottom of the editor, and you will be directed to a screen where you can enter the details of the page. As you can see in Figure 3-9, you can select the page you want to display from the Page drop-down button. This drop-down list will display all the pages available, so you can select the required one. If the page you want to display is an external page, then you can specify the URL of the external page.
Note that the publishing state is to define whether the link is published or not. The final four properties are all related to link images. For instance, if you want to display an image instead of text, you can specify the URL of the image and other properties such as width, height, and alternate text of the image.
Figure 3-9
Adding a new link form
Once you click the Save button, notice that the new page will appear in the Edit Primary Navigation editor. Click the Save button in the editor to confirm the addition of the new link. You can now see that the navigation has been edited per your requirements (Figure 3-10).
Figure 3-10
Updated navigation
To add a child page, make sure that you deselect the “Display page child links” checkbox in the “Add new link” form and click Save. In the editor, drag the child page under the parent page, as illustrated in Figure 3-11.
Figure 3-11
Inserting a child
Applying a Theme
Most of the time developers are compelled to change the theme of a portal to enforce the branding of the business. There are many themes available, but to keep things simple, this book will guide you in applying a simple theme from Bootswatch.
Important
At the time of writing this book, the out-of-the-box theme of Dynamics 365 portals is based on Bootstrap version 3 from Bootswatch. So, you should download the Bootstrap theme from https://bootswatch.com/3/.
When you open the Bootswatch page, there are several free themes that you can download. First, download your preferred theme. As shown in Figure 3-12, click the “Child file” option.
Figure 3-12
Creating a new child file for the theme CSS file
This action will open the “Create a new child file” form where you should enter the details of the theme file (Figure 3-13). After adding the information, hit the Save button, which will create a web file in Dynamics 365 CE portal admin application with the CSS file as an attachment to the notes.
Figure 3-13
Applying a theme
Make sure that you enter the Name as “bootstrap.min.css” and copy the same to the Partial URL field as seen in Figure 3-13.
If you go to the web files, you can see the bootstrap.min.css file is listed (Figure 3-14).
Figure 3-14
Bootstrap CSS in web files
Open the bootstrap.min.css record and open the Notes tab. You can create a new note and attach the new theme file, as shown in Figure 3-15.
Figure 3-15
Bootstrap CSS attached to notes
Once the changes have been applied, you can refresh the portal to see the changes. Sometimes changes might not be visible with a simple refresh. In such situations, navigate to the portal Admin Center and open Portal Actions. Click Restart, and the new theme will be applied (Figure 3-16).
Figure 3-16
Home page after applying the theme
You can see the changes more clearly when you navigate to the sign-in page (Figure 3-17).
Figure 3-17
Sign-in page after applying the new theme
Adding Pages and Customizing Pages
To create a web page, go to the Web Pages option in the Content section of the right pane. Then click the +New button to create the new page (Figure 3-18). At this level, we will just be creating a placeholder. Later in this chapter, we will be adding a list to show the available events created in the system.
As previously explained, open the navigation editor and change the page to the new page you created; save the changes (Figure 3-19). As a best practice, you should first create the pages you want and update the navigation accordingly. Next, we will look at adding an entity list to the web page and loading some data. As of now, the page that you created is a blank page.
Figure 3-19
Changing the page
Creating Entity Lists
Entity lists are used to render the list of records stored in a Dynamics 365 CE entity. Even power users can easily configure an entity list without developer help. The grid that lists the records is capable of the following:
The grid can sort records.
If the number of records exceeds the page’s specified page size, it will automatically apply pagination.
The entity list also supports multiple views in a scenario where multiple views have been specified.
If you have specified a web page for a detailed view, then each record will contain a link to the details page. When you click the link, the record ID will be appended to the query string to load the details page.
Also, records can be filtered if values exist for the Portal User and Account attributes. The grid will render a drop-down list to facilitate the filtering.
The most important thing to remember is that an entity list must be associated with a web page for the list to be visible on the portal. To create the entity list, under the Content section of the right pane, click the Entity Lists option. Click +New to create a new entity list (Figure 3-20). After adding the primary information, click Save. There are many other properties available on this form, and as you can see, there are multiple views specified to view both active and inactive events. For a full list of attributes and relationships, please visit https://docs.microsoft.com/en-us/dynamics365/customer-engagement/portals/add-webpage-render-list-records#entity-list-attributes-and-relationships.
Figure 3-20
Creating an entity list
Now that we have created a simple entity list, let’s add it to the web page created. As shown in Figure 3-21, add the entity list and save it.
Figure 3-21
Adding the entity list to the web page
After saving these changes to the web page, add the access control rules for the web page (Figure 3-22). In Chapter 2, we created a rule specific to events management.
Figure 3-22
Web page access control rule for events page
Make sure the relevant web roles are added to the access rule as well. Also in Chapter 2, we created the entity permissions, which will determine what the user can do with the records. Once all these settings are configured, navigate to the new page, and you can see the list of events created in the Dynamics 365 CE being displayed in the portal (Figure 3-23).
Figure 3-23
Event entity list displayed on a web page
Note
As explained earlier, you can see that the entity list has pagination and sorting enabled on it.
Next, let’s create a details page.
Creating a Details Page
A details page can be created with both entity forms and web forms. For this example, we will create an entity form to display the event details page. Navigate to Entity Forms under the Content section in the right pane. Click +New to create a new entity form. Enter the basic settings on the General tab. You must select the entity name and the form name from the drop-downs on the right. If you have a specific form that is designed for portal users, you can select it from this drop-down. If you want to display a specific tab, you can select it from there.
Mode determines the purpose of the form. In this example, the value selected was ReadOnly, meaning that the form will only display the details, with no editing allowed. Record Source Type is where you specify where to get the record to manipulate using the form. Since this is a details view, the value should be Query String. This setting requires the parameter to be passed via the query string of the URL to the form. This parameter is specified in the Record ID Query String Parameter field, as illustrated in Figure 3-24.
You must select the SBMA events and the parent page that has the event entity list.
Save the settings, open the entity list, and scroll down to the property Web Page for Details View. Select the web page you have just created (Figure 3-25).
Figure 3-25
Setting web page to display the data
Save the changes and refresh the portal site. You can see, the field Event Code is highlighted in blue, meaning that it is a hyperlink to open the details about each event record (see Figure 3-26).
Figure 3-26
Entity list after mapping the details form
When you click the link, it will take you to the details page. The most important thing to remember here is that since you have set this form as a view-only form, if your form has any field with editable fields, those fields will not be visible on this form. For instance, if you have selected one of the main information forms in CRM and if the fields are read-write, then none of the fields will be displayed. Therefore, you must create another form in the CRM system with read-only fields and select that form in the entity form settings. As shown in Figure 3-27, the fields of the Dynamics 365 CE form is read-only.
Figure 3-27
Dynamics 365 forms with read-only fields
When you open the details page in the portal, you can see the fields are read-only as well (Figure 3-28).
Figure 3-28
Event details page
Creating a Form
Similar to creating the details page, a create form can be configured with entity forms. Unlike the details form, you must select the mode as Insert, which indicates this entity form is for creating or inserting new records. So, as the first step, create the entity form and provide the required information, as shown in Figure 3-29.
Next, go to the Event Entity List record, and on the Options tab, scroll down to the Grid Configuration section of the form (Figure 3-31). This will allow you to define the view actions. Click +Create and select the entity form that you created in the previous step.
Figure 3-31
Grid configuration, Create button
Save the settings and navigate to the Events list, and you can see that the new +Create button appears on top of the view, as shown in Figure 3-32.
Figure 3-32
Create button on the view
Click the button, and a new pop-up window will appear to enter the event details (Figure 3-33).
Note
As you may have noticed, this create event form is not associated with a web page. This is simply because the form is associated with the view.
Figure 3-33
Create form
To select the lookup values, click the magnifying glass, and it will display the lookup selector, as shown in Figure 3-34.
Figure 3-34
Lookup value selection window
Editing a Form
Similar to creating the create record form, we can create a new entity form and set the required settings as per our requirements. Select Edit from the Mode property, as shown in Figure 3-35.
Note
In Figure 3-35, you can see that the Portals – Create Event form is selected. You have the option to create a specific form just for editing by exposing only the fields that can be edited by the portal users. Also, if you are setting the entity references, you must make sure the user has the appropriate entity permissions (Read, Append, and Append To). Otherwise, the user will not be able to edit or create the record since the users do not have permission for the referencing entity.
Figure 3-35
Edit form settings
To enforce security, click the Enable Entity Permissions checkbox so that the users with event administration rights will be able to edit the event details. Next, open the entity list, navigate to the Options tab, click +Edit to add the edit button, and select the entity form created for editing the record (Figure 3-36).
Figure 3-36
Adding edit form settings to the entity list
In the portal, clicking the event code will open the edit form where users can edit the records and submit the changes (Figure 3-37).
Figure 3-37
Edit form
What if the user does not have edit permissions for the record? When the user clicks the record to edit, the message shown in Figure 3-38 will be displayed.
Figure 3-38
Error message when the user does not have appropriate permissions
Adding Charts to the Portal
Sometimes users want to see some graphical representation of data within the portal. Charts can be used to facilitate such requirements. In Dynamics 365 CE, you can easily create charts, but how can you display those charts in your portal? In the following scenario, the event administrators would like to see events by status alongside the list of events on the page. You can do this by just adding one line to the web page. For this, you will have to use Liquid templates, which we will be discussing in detail in Chapter 5 and Chapter 6. First, open the web page where you want to place the chart and paste in the following line of code, as illustrated in Figure 3-39.
Note
The chart ID and view ID values should be replaced with the actual values.
You can also add the Liquid line by opening the web page in the portals Dynamics 365 CE portal admin application and scrolling down to the inline grid where it lists the localized content (Figure 3-40).
Figure 3-40
Localized content
Open the entry, scroll down to the Content section, and enter the Liquid line, as shown in Figure 3-41.
Figure 3-41
Content editor, CRM portal app
Save the settings and refresh the portal page to see the results (Figure 3-42).
Figure 3-42
Chart displayed on the web page
You should always make sure the visiting user has the appropriate access rights; otherwise, the chart will not be visible to the users (Figure 3-43).
Figure 3-43
The user does not have appropriate permission to view the chart
Performing Validations
When capturing the data using forms, you must use proper validation techniques to ensure the integrity of the data. Incorrect data may result in unexpected behavior or erroneous outcomes in the business processes. In this section, you will look at some validation techniques that can be used with Dynamics 365 portals.
With Dynamics 365 CE configuration, you can enforce some validations, such as checking the length of a value entered in a field, setting fields as Business Required, and so on. For instance, when you set a field as Business Required in a Dynamics 365 CE form, the same validation will be rendered to the web form as well (Figure 3-44). As you can see in the figure, there are a few fields that are mandatory.
Figure 3-44
Mandatory fields on the Dynamics 365 CE form
Now, if this form is set up as an entity form in the portal, all the fields which are configured as mandatory in Dynamics 365 CE will also be mandatory on the entity form (as shown in Figure 3-45).
Figure 3-45
Mandatory field validations
As shown in Figure 3-46, there is a validation on the Dynamics 365 CE form to check whether the start date of the event is greater than the end date. This validation is implemented using business rules.
Figure 3-46
Business rule validations on Dynamics 365 CE form
But when you enter the details in the entity form in the portal, the start and end date validation will not work. As you can see in Figure 3-46, the on-change event will trigger the validation on the Dynamics 365 CE form. Let’s enter the information via the entity form in the portal (Figure 3-47).
Figure 3-47
Creating event records, with start and end date validations
No validation gets triggered, and the record gets saved straightaway. At the time of writing this book, the business rules are not rendered in Dynamics 365 portals. As you can see in Figure 3-48, there are two records saved with incorrect start and end dates.
Figure 3-48
Event records saved where the start date is greater than the end date
This is where you can use JavaScript/jQuery validation on entity forms to eliminate incorrect data entry via the portal.
Our objective here is to notify the user when they enter incorrect data. In the entity form settings, you will find the Custom JavaScript field on the Additional Settings tab. This section is at the bottom of the form, so you will have to scroll down. Enter the validation code shown in Listing 3-1 in the editor.
var startDate = new Date($("#sbma_startdate").val());
var endDate = new Date($("#sbma_enddate").val());
if(startDate > endDate)
{
alert("Start date cannot be greater than end date.");
return;
}
};
}
}
}(window.jQuery));
}
Listing 3-1
Start and End Date Validation Code
Now on the entity form, when you enter the wrong date range and hit Submit, the validation message will pop up (Figure 3-49).
Figure 3-49
Incorrect date range validation message
Until the user enters the correct value range, the validation will trigger.
Summary
This chapter explained how to modify the look and feel of a portal and how a portal can be configured to list and enter data. In this chapter, I covered applying themes, editing the content, adding entity lists, and creating entity forms. Also, I covered how entity forms can be associated with a list to enter and edit data. In the next chapter, we will be looking at another interesting customization known as web forms, and I will cover how to bind the portal with SharePoint for document management.
