Dynamics 365 Portals is a Software as a Service (SaaS) portal natively integrated with Dynamics 365. This is a great addition to Dynamics 365 to provide customer, partner, or employee portal capabilities. Since it’s a SaaS product, developers won’t get access to the server-side code base to be able to customise the portal. Dynamics 365 Portals use an open source template engine “Liquid” to allow developers to create custom templates without needing access to the server-side code. In this blog series, I will walk you through series of basic to advanced examples of using Liquid to create custom templates.
Dynamics 365 Portal OOTB Features
Dynamics 365 Portals can be provisioned as one of three portal types and includes a number of features.
- Self-Service Portal
- Knowledge Management
- Help Desk/Case Management
- Community Portal
- User Profile Management
- Forums
- Ideas
- Event Management
- Partner Portal
- Customer Management
- Opportunity Registration
- Opportunity Distribution
- Employee Access Management
There are add-on solutions you can install to integrate with Dynamics 365 Field Service and Project Service Automation apps.
- Field Service
- Project Service Automation
While Dynamics 365 Portals come with many features OOTB, Portal can also be configured and extended to create your own forms, views, and templates as well.
Often we would need to customise the portal to provide unique customer experiences which standard configuration capabilities fall short. Liquid Templating capabilities become handy for these scenarios.
Page Structure
Before jumping into write code, it’s important to understand the relationship between pages, page templates, and web templates.
A Page is where specific content is displayed.
In this diagram, you can see that a Page should be associated with a Page Template. A Page Template can be associated with a Web Template. In other words, one Web Template can be used by many Page Templates and one Page Template can be used by many Pages.
Now, technically, a Page Template doesn’t have to be associated with a Web Template. It can be associated with a physical ASPX page which resides on the server. If there’s an existing ASPX page template which is suitable for your needs then you can simply use that. You don’t have to use Web Templates.
Web Templates vs Page Templates
A Web Template and a Page Template are both records in Dynamics 365. The difference is that a Page Template is just a pointer to where the Template is stored. A Web Template, on the other hand, includes the actual coded design on the record itself. Because of this, the code can be accessed from the UI or even programmatically via SDK or API.
When a page template is based on a server-side ASPX page template, then the type must be set to “Rewrite”. The Rewrite Url field must also be populated.
When a page template is based on a Web Template, then the type must be set to “Web Template”. The Web Template lookup must also be populated.
In this series, we are only focusing on Web Templates.
What is Liquid Template Language?
Now that you understand, pages, page templates, and web templates, it’s time to look at Liquid. Dynamics 365 Portals use an open source template engine called “Liquid” to allow developers to create custom templates without needing access to the server-side code. I will walk you through series of basic to advanced examples of using Liquid to create custom templates.
Liquid is an open-source template language created by Shopify and originally written in Ruby. The code base was ported to .NET as an another open-source project called DotLiquid. Dynamics 365 Portals (formerly Adxstudio) use DotLiquid as the Liquid Template Engine of their portal. You can look at Shopify documentation even though some parts are specific to Shopify. The OOTB Web Templates are also useful learning resource to write Liquid statements.
To use liquid, you don’t need access to the server. The code is stored in the database in a record and renders directly from the database.
Where can I use Liquid?
You can use liquid to create Web Templates, inside Copy (HTML) field of a Web Page, or in Code Snippets.
Liquid Basics
Let’s look at some of the basics of Liquid.
Tags – Liquid tags are the programming logic that tells templates what to do. Tags are wrapped in: {% %} characters. Some tags can take parameters. Examples: if unless else elsif case and or for cycle tablerow include assign increment.
Objects – Liquid objects contain attributes to output dynamic content on the page. For example, the page object contains an attribute called title that can be used to output the title of a page. Liquid objects are also often referred to as Liquid variables. To output an object’s attribute, wrap the object’s name in {{ and }}.
Filters – Filters are simple methods that modify the output of numbers, strings, variables and objects. Some examples are.. concat, first, last, order_by, size, skip, where, minus, plus, modulo, upcase, downcase, truncate. Here’s an example…
In this example, if else and endif are tags. User is an object. This object has an attribute called firstname. This user object represents the logged in portal user. A portal user is a contact record in Dynamics 365. Therefore, you can access any field in contact entity via user object. Downcase is a filter. It takes the output of user.firstname and then converts it to lowercase.
Creating the first Web Template – Hello World!
Step 1 – Create a Web Template
Let’s learn how to create a web template. Navigate to Portals > Web Templates.
Click + New to create a new Web Template. Give it a name, select the website the web template will be associated to, and write the code in Liquid.
Click Save.
Code Snippet
|
1 2 3 4 5 |
{% if user %} Hello, {{ user.firstname }} {% else %} Hello World! {% endif %} |
In this Liquid statement, we say if the user object is not null, then display Hello, which is a static text and then display the firstname of the user. If the user object is null, then display the static text Hello World!
Step 2 – Create a Page Template
Now, to see this web template you need a page. A page needs a page template. So the next step is to create a new page template. Navigate to Portals > Page Templates.
Click + New to create a new Page Template. Give it a name, select the website the page template will be associated to, select Web Template for Type, and select the web template you just created in the Web Template lookup.
Click Save.
Step 3 – Create a Page
Let’s create a Web Page. Navigate to Portals > Web Pages.
Click + New to create a new Web Page. Give it a name, select the website the web page will be associated to, select the Parent Page, type the partial URL, select the Page Template, and select the Publishing State “Published”.
Click Save.
Now we are ready to test our first Web Template. Navigate to https://yoursitename.microsoftcrmportals.com/wp-module1/
You’ll see “Hello World!”.
Now, login to the portal. The Hello World text is now changed to Hello, Nadeeja.
Congratulations! You have created your first Web Template using Liquid. In the next modules, we’ll go through more complex Web Templates.
Quick Tip: You can use the Portal Code Editor in XrmToolBox to edit all portal code including Liquid, HTML, CSS, and JavaScript. XrmToolBox includes a ton of tools and it’s getting better every day.
In Dynamics 365 Portals – Liquid Templates – Part 2 – Retrieve Data, I’ll demonstrate how to retrieve records using Liquid.
In Dynamics 365 Portals – Liquid Templates – Part 3 – Retrieve Data using FetchXML, I’ll demonstrate more advanced examples of using Liquid to retrieve records using FetchXML.
References
Shopify Liquid Documentation – http://shopify.github.io/liquid/
.NET Port – DotLiquid – https://github.com/dotliquid/dotliquid
Thank you for visiting Dyn365Apps.com.
Follow me on Twitter to get the latest news, tips and tricks and more …
Until next time…
About the Author
Nadeeja Bomiriya is a Microsoft MVP, Chapter Lead – CRM Saturday – Australia, President – Melbourne Dynamics 365 User Group, Technical Architect, and Dynamics 365 Practice Lead who lives in Melbourne, Australia.