Tutorial 2: Designs, Layouts & Templates

In Content Tutorial 1 we covered how to create and organize content in the backend – and in this tutorial we will cover the basics of rendering that content in the frontend.

We will be covering:

  • How to create a new design from scratch and use it
  • How to install and use external design templates – and how to make them dynamic

But first, a bit of terminology:

  • A design is a collection of layouts (master.cshtml, index.cshtml, etc.)
  • A layout is a dynamic HTML file containing markup governing, well, the layout of a webpage
  • A paragraph template is a layout file governing the layout of paragraphs

Page layouts are made dynamic by using content placeholders and navigation placeholders to define places in the HTML where content from Dynamicweb should be rendered.

Paragraph templates and module templates are made dynamic by using template tags –like ParagraphText – to render paragraph content where you want it.

Ok, so let’s get started.

A design is defined by a subfolder to Templates/Designs – so to create a new design simply:

  • Open your files area and fold out the Templates folder
  • Right click the Designs folder and click New subfolder (Figure 2.1)
  • Name the subfolder (this will be the name of your design)
Figure 2.1 Creating a subfolder in the Designs folder

And that’s it – the content pane will change to show the contents of your new design folder. Or the absence of content, as it were.

And without one or more layouts your design is pretty useless.

A page layout is an HTML file which defines how the content you create and organize in the backend should be presented in the frontend.

To create a page layout file:

  • If you’re not already there, navigate to your Templates/Designs/MyDesign folder
  • Click New file in the ribbon bar (Figure 3.1)

 

Figure 3.1 Creating a page layout in Razor
  • Name your layout – e.g. index.cshtml. You must use the .cshtml extension.
  • Click OK

This will open an editor with an barebones shell of an.cshtml file – if it doesn’t open just right click it and select Edit.

Replace the html with the code below to the file, then save and close.

<!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1.0"/> <title>My design</title> <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.3/css/bootstrap.min.css"/> </head> <body> <div class="container"> <h1>My design</h1> </div> <script src="https://code.jquery.com/jquery.js"></script> <script src="//netdna.bootstrapcdn.com/bootstrap/3.0.3/js/bootstrap.min.js"></script> </body> </html>
  • Right-click the file and click preview – this opens the file in frontend, where you should see a blank page with a h1 headline saying ‘My design’.

Hurrah! You’ve created a (static) page layout.

Where a page layout defines where on a page your content and navigation will be rendered, a paragraph template defines how paragraph content is rendered.

To make sure there is always a paragraph template available, create a default paragraph template to fall back on:

  • Go to Files/Templates/Designs
  • Right click your design folder and click New subfolder
  • Name the folder ‘Paragraph’
  • Create a new Razor file – name it Default.cshtml
  • Replace the default code with the following code:
<div> <div> @GetValue("ParagraphText") </div> <div> @GetValue("ParagraphImage") </div> <div> @GetValue("ParagraphModule") </div> </div>

Since paragraph templates are merged with your page layout before being rendered, it is not necessary define a <head> or <body> node.

The default.cshtml template will be selected by, well, default for paragraphs using your design – but you can create other paragraph templates and select them manually when creating paragraphs. If no default.cshtml template is found, the first template in the MyDesign/Paragraph folder is used – and if that folder does not exists or is empty, the first template in /Files/Templates/Paragraph will be used.

Since this is the only layout in your design, it makes sense to make it the default layout for your website.

To make your website use the new design:

  • Open your website settings (Apps > Websites > YourWebsiteName)
  • Switch to the Layout tab
  • Using the Layout dropdown (Figure 5.1), select your page layout
  • Save 
Figure 5.1 Using the design in websites settings

Applying a design to a website has two effects:

  • All new pages created on the website will use this layout by default
  • Only layouts in the MyDesign folder can be selected when you want to override the default layout for a page

Ok, so the layout you created is not very exciting – and it’s not very useful either since it’s static, which means that the content you create in your Dynamicweb backend is not yet rendered in your frontend.

To change that, you must define placeholders – locations in the html where e.g. Dynamicweb paragraph content is rendered, or dynamic navigation is generated.

A content placeholder can be any html element in the layout template, and you can define as many placeholders as you like. You do so by applying a CSS class to the html you want to make dynamic.

The placeholders available to you are:

  • dwcontent – for generating dynamic content
  • dwnavigation – for generating dynamic navigation

To make your index.cshtml layout dynamic:

  1. Go to Files > Templates > Designs > MyDesign
  2. Right-click your layout and click Edit
  3. Add a new <div>-tag with the dwcontent class, and id, and a title of some sort to your layout
  4. Add a new <ul>-tag with the dwnavigation class, and id, and settings="startlevel:1;endlevel:1;template:LIClean.xslt" to your layout:
  5. Save the layout

Your layout should now look something like this:

<!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1.0"/> <title>My design</title> <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.3/css/bootstrap.min.css"/> </head> <body> <div class="container"> <ul class="dwnavigation" id="navigation" settings="startlevel:1;endlevel:1;template:LIClean.xslt"> </ul> <h1>My design</h1> <div class="dwcontent" id="content" title="content placeholder"> </div> </div> <script src="https://code.jquery.com/jquery.js"></script> <script src="//netdna.bootstrapcdn.com/bootstrap/3.0.3/js/bootstrap.min.js"></script> </body> </html>

Go back to your content area and click the Show Page button to verify that you can now see (Figure 6.2):

  • The text and image from your paragraph
  • A menu based on your page structure
Figure 6.2 Page with a design and menu

So that’s pretty cool – and (I hope) educational – but in real world scenarios it’s a little more useful to download an existing design and hook it up to your solution.

So that’s what we will be doing next :-)

Ok, so you now know how to create a design from scratch, let’s see how easy it is to download an existing design example and make it dynamic:

  • Download the One Page Wonder design files
  • Open your file manager and navigate to Files/Templates/Designs
  • Click the upload manager button in the ribbon bar to open the upload manager (Figure 7.1)
Figure 7.1 Upload manager
  • Click Choose file and select the zip you downloaded
  • Check the Extract Archives
  • Click Upload

The zip file will now be uploaded and extracted – but to be able to view it you must double click the Files area button – this will cause the Files tree to reload and your new design folder will show up.

You will probably have a folder inside a folder – move the folder with actual content a level out, and rename it to something less cumbersome than startbootstrap-one-page-wonder-gh-pages.

And that’s it – you are ready to get down to business!

This first thing you should do is switch design on your website so that it uses the design you just uploaded.

After that it’s business time. Your uploaded design must be broken down and made dynamic:

  • Use dwnavigation to make the navigation dynamic
  • Use dwcontent to make the page content dynamic
  • Move relevant parts of the static html to paragraph templates – and render the paragraph content using the same Razor commands you used when creating your Default.cshtml paragraph template

During this exercise you will probably need to use the following command in your templates:

@TemplateTags()

It will render a list of template tags (e.g. ParagraphText) and their values (e.g. <p>MyParagraphText</p>) each time the template containing it is used to render something. This is incredibly useful, and something you will be doing a lot when working with Dynamicweb.

And remember to have fun!

If you are unfamiliar with the concept, master pages are a useful way of ensuring a consistent look across a series of layout templates.

Rather than having your navigation and footer – and all other shared elements – in every layout file, you can add them to a master page and import them with an @MasterPageFile(“master.cshtml”) command at the very top of your layouts.

Create a master page containing:

  • Your navigation
  • Your footer
  • Any other element you want to share (e.g. meta information, CSS, JS)

In your master page, add @ContentPlaceholder() where you want the page layout files to be merged with your master page.

During Tutorial 2 you have learned:

  • How to create a design from scratch and use it on a website
  • How to upload an existing design to your solution
  • How to break a static design down in Dynamicweb pieces, like a layout and various paragraph templates
  • How to create and use a master page for shared design elements

Now, unless you use really hacky solutions, you will not be able to mirror the design you downloaded completely – for instance, you only have access to one ParagraphHeader so it’s difficult to recreate the two-colored headlines from the One Page Wonder design.

And if you wanted to create a blog post with information about the author, several images, and a list of related posts you would have to either do a lot of formatting inside the rich text editor or create a lot of different paragraph templates.

Neither of these options are particularly appealing – which is why our next tutorial will cover Items – custom content types (pages, paragraphs, and more) defined by a content designer:

  • Create item-based paragraphs and pages, containing exactly the fields you need for a particular purpose
  • Use items to extend website settings, page settings, user groups & users with custom fields
  • Use the item publisher and item creator modules to allow non-backend users to create content – and publish it in frontend