DynamicWeb templates in Razor

Server-Side Rendering using Razor templates

Templates in DynamicWeb are used for rendering content into the browser and creating the actual website.

The templates are based on Razor and to build an entire website in DynamicWeb, multiple templates are rendered individually and combined into a complete webpage.

A page in DynamicWeb will consist of a layout template, one or more navigation templates, and then a number of templates for all the content such as text, images, navigations, product list and so on.

Full design freedom - free framework freedom

All markup, CSS and javascript is coming from the templates - there is a complete separation of rendering and content.

Any CSS and Javascript can be used. The only requirement is the use of Razor templates.

The frontend stack can be anything you desire and you can use build tools, node, npm, bundlers, minifiers etc.

Prerequisites

DynamicWeb solution installed locally
An IDE for template development that supports Razor, i.e. VS Code or Visual Studio
Experience with HTML, CSS, Javascript
Experience with Razor
Basic understanding of DynamicWeb and its concepts
Optional: knowledge of GIT, NPM, Bundlers, Sass, Typescript and other frontend technologies

Introduction

Quick introduction to Razor, template file structure and basic concepts

Razor

Razor is a markup syntax for embedding .NET based code into webpages. The Razor syntax consists of Razor markup, C#, and HTML. Files containing Razor generally have a .cshtml file extension

Example Razor template

@inherits Dynamicweb.Rendering.ViewModelTemplate<Dynamicweb.Frontend.PageViewModel>

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>@Model.Title</title>
  </head>
  <body>
    <h1>Welcome to the page '@Model.Name'</h1>
  </body>
</html>

In the example above, most of the code is markup - and a view model from DynamicWeb is injected and can be used for dynamic content.

The result of the rendering would be this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>DynamicWeb - CMS, PIM and Ecommerce</title>
  </head>
  <body>
    <h1>Welcome to the page 'Home'</h1>
  </body>
</html>

Viewmodels and template tags

DynamicWeb has 2 types of viewmodels that are passed into templates.

ViewModels
Template tags

Viewmodel templates are a newer approach and type safe. Template tags are an older approach and are being phased out - but are still in use.

A ViewModel-based template:

@inherits Dynamicweb.Rendering.ViewModelTemplate<Dynamicweb.Ecommerce.ProductCatalog.ProductListViewModel>

<h1>@Model.Group.Name</h1>

<ul>
@foreach (var product in Model.Products)
{
    <li>@product.Name (@product.Price.PriceWithVatFormatted)</li>
}
</ul>

A tag-based template:

@inherits Dynamicweb.Rendering.RazorTemplateBase<Dynamicweb.Rendering.RazorTemplateModel<Dynamicweb.Rendering.Template>>

<h1>@GetString("Ecom:ProductList:Page.GroupName")</h1>

<ul>
@foreach (LoopItem product in GetLoop("Products"))
{
    <li>@product.GetString("Ecom:Product.Name") (@product.GetString("Ecom:Product.Price.PriceWithVATFormatted"))</li>
}
</ul>

Template file structure

Templates are physically stored on disk and are organized and named in a specific structure that has to be followed.

Each type of template belongs to a folder with a specific name and a specific place in the structure.

Below a simple example of a template structure. All templates will always be under the /Files/Templates folder.

/Files/
├── Templates/
│   ├── Designs/
│   │   ├── myDesign/
│   │   │   ├── Paragraph/
│   │   │   │   ├── image.cshtml
│   │   │   │   ├── text.cshtml
│   │   │   ├── Navigation/
│   │   │   │   ├── topNavigation.cshtml
│   │   │   │   ├── leftNavigation.cshtml
│   │   │   ├── myLayout1.cshtml
│   │   │   ├── myLayout2.cshtml
│   │   │   ├── myMaster.cshtml

A design (myDesign above) is a 'root' folder for a group of templates that is used to render an entire website. Dynamicweb can have multiple websites using different designs.

Inside a design there are layouts (containing the overall markup like <head> and <body> sections) - that would be the myLayout1.cshtml and myLayout2.cshtml templates above. They contain two different layouts - i.e. one with a top navigation and one with a left navigation. They will both be using the PageViewModel viewmodel.

The design folder contains subfolders for other types of templates - Paragraphs and Navigation. Each of these folders contains templates specific for that type of content. The paragraph templates will be using the ParagraphViewModel and the navigation templates will be using the NavigationTreeViewModel

Each functionality and app in Dynamicweb will have its own subfolder with viewmodels or tags specific for that functionality.

Development environment

To do

Designs & Layouts

Designs and layouts is where all your design and website will come from. Read this guide to do a full implementation of a DynamicWeb design using Razor templates

Extensibility

Viewmodels in Dynamicweb contain the content needed to render the website.

Using razor and C# gives you a powerful option to extend what is coming out of the viewmodels.

C# code can be used in different ways

Create extension methods for viewmodels that can simplify the markup
Use Dynamicweb API to get additional data from i.e. pages, users, products etc.

Extending templates can be a powerful tool - but that power comes at a cost. Consider these things when extending the templates

Use extensions for rendering logic - i.e. if things should be wrapped in <h1> or <h2> or if a label should have one or another text depending on a value etc.
Separation of concerns - be careful not to add 'business logic' in the template. I.e. how prices are calculated or who can see what. Use other extensibility points for that, i.e. PriceProviders, permisions etc.
Creating extension methods for code only used once compiles the code away so it is harder to update and harder to understand how the template work.
Too much C# code and API calls can cause performance issues if not used carefully. Templates are rendered and the contained code executed many times all the time, so the code has to be fast and well crafted.

Read more about viewmodel extensibility in the Extending viewmodels section

Read more about providers in the Extending providers section

Read more about notifications in the Extending notifications section

Table of Contents