Updated: Jan 3, 2019
Recently, a customer identified a need for custom navigation in the Dynamics Portal to allow end users to apply for state programs using an application process with 26 “pages” of information. Users applying for the programs needed to be able to skip around within the application, returning to various pages several times throughout the process to provide information. Thus, they needed custom navigation to enable jumping directly to a specific page.
Using web forms in the portal was not an option; you can only move forward or backwards in the standard portal navigation with web forms, no jumping around. Thus, the navigation for selecting which of multiple pages to open was going to have to be written from scratch!
Ultimately, the solution was relatively simple—provide a dropdown that includes every step in the application process, in order, and allow the end user to select the “step” to open that page:
Each step in the process has an associated Entity Form step—a create, an edit and a read-only version of that step. To make it simple, we’ll name each step with the process, the entity, and the step—for example, “create_app_step_1” or “edit_app_step_2”. This makes it easy to identify in a long list of entity forms, 53 in all (26 each for edit and view, but we only need one “Create” step; more on that later).
Once completed, the user could either select “Home” in the navigation and return to the main portal page or click “ready to submit” on the last page of the application to submit their application for review.
Luckily, this challenge is rather easy to solve with just a bit of HTML, a custom Entity, some CSS, and the “secret sauce” … the Liquid Scripting language!
(To keep this blog post as short as possible, I’m assuming here that the reader has some familiarity with Entity Forms and Web Pages in the Dynamics 365 Portal implementation. If you don’t, please familiarize yourself with Entity Forms here, and Web Pages here).
The HTML for this (in conjunction with the CSS classes – more on this later) is easy; we have only to provide a div tag around the code to “identify” the drop-down, a button tag to decorate it with some formatting appropriate to a drop-down, and a standard unordered list. Here’s the resulting static HTML:
The secret to all of this is in the lines between the <li> and </li> tags. We need to render these lines dynamically; this is done using a custom entity, and Liquid code. The process parameter in the URL refers to the process as defined in the navigation entity. More on the Liquid code in just a bit; for now, let’s focus on the custom entity.
The Custom Navigation Entity
The navigation entity is also rather easy to create. We simply need 1) the process that the navigation is related to (use an option set for this), 2) the partial URL of the step, 3) the description of the step, and 4) a sequence to order the navigation with. We’ll call this entity “Portal Navigation” and use the default preface of “new” for the fields. Here’s a sample of the data that we should put in the new entity (use advanced find to quickly edit this entity):
Note that in the 1st step to create the app, we use the “create_app_step_1” partial URL and all other steps are edit steps.
Until now, this implementation has primarily used some well-known technologies: HTML and a custom CRM Entity. Now that the custom entity is created, let’s look at how we’ll render the dynamic HTML using the Liquid Scripting Language, which is relatively new to CRM developers.
Remember I touched on only needing one “Create” step? Initially, I had used “create” types for all steps and was quickly rewarded with 26 new records! Don’t do that! Use a create type in your initial entity list step and edit types for all subsequent steps. The only exception to this rule is the “view” process; every step in that process should be a “read only” entity form type.
Using the Liquid Scripting Language to render the HTML
Here’s where we come to what I consider the most exciting part of this implementation: the Liquid Scripting Language! Liquid is not unique to the Dynamics Portal; it’s been around for a while. It is an open-source templating language created by Shopify in 2006. It was initially used by ADXStudio in their Portal offering for CRM. Upon Microsoft’s purchase of ADXStudio in 2015, the offering was incorporated into Dynamics 365 as the Microsoft Portal, and Liquid Templating was included as well. This is exciting for those of us in Dynamics Development, as it provides a robust method of writing templates that can render dynamic results. Since it is open-source, the language is constantly evolving. Here is a great tutorial on the liquid templating language as it is implemented in the Dynamics Portal engine.
To implement the new custom navigation, the first thing we need to do is modify the standard web template called “Layout 1 Column”. That template is straightforward and already includes some Liquid. The line to insert is highlighted below:
This line is again, straightforward. It’s simply an include statement that places the navigation elements into the overall page template. Thus, the drop-down is rendered at the top of the page.
As you can imagine, the “dropdown navigation” template is a bit more involved, but it’s not that bad. First, pull all the values out of the query string and assign to parameters.
Then, if the process parameter has been included in the query, we’ll make a call to include the FetchXML data and assign it to the categories variable.
The Fetch Navigation Data include file is presented below. It simply makes a standard FetchXML call to get the data from the custom Navigation entity using the process that we are focused on. The results of this Fetch call are returned in the parent_categories variable.
Back to the “Layout 1 Column” file. With the fetch results obtained, we then check that results were indeed returned, write out our static HTML, iterate through the results that were returned, and render the dynamic HTML.
Finally, if the process parameter was NOT included, we remind the developer to provide it.
Tying it all together with Cascading Style Sheets
Finally, to get all of this to work, we use dropdown styles that were already coded in the standard Bootstrap style sheets. If you don’t know – Bootstrap is an open-source front-end framework that contains Typography, forms, buttons, navigation and other UI components, as well as a templating layout for your website. Portal uses it out of the box to render pages, and as it is an industry standard, it provides for a simple and extensible way to render websites.
The Final Web Template
Putting it all together, here are the complete “Dropdown Navigation” and the associated “Fetch Navigation Data” files:
Fetch Navigation Data