Working with Templates

Templating in Umbraco builds on the concept of Razor Views from ASP.NET MVC.

Templates are the files that control the look and feel of the frontend of your Umbraco websites. Building on the concept of MVC Razor Views, template files enable you to structure your websites using HTML, CSS, and JavaScript. When tied to a Document Type, templates are used to render your Umbraco content on the frontend.

Each Template is a cshtml file in the Views folder of your project directory. You can also manage Templates from the Settings section in the Umbraco backoffice.

Generating a template alongside a new Document Type and making quick changes during local development work well in the backoffice. For ongoing work, maintain templates as .cshtml files in the Views folder using an IDE, and keep them in source control. For more information, see Managing Views and Assets.

Creating Templates

When building an Umbraco website you can automatically generate Templates when you create a new Document Type. This will ensure the connection between the two and you can jump straight from defining the content to structuring it.

Choose the option called Document Type with Template when you create a new Document Type to automatically create a Template as well.

In some cases, you might want to create independent Templates that don't have a direct connection to a Document Type. You can follow the steps below to create a new blank Template:

1. Go to the Settings section inside the Umbraco backoffice.
2. Click ... next to the Templates folder.
3. Choose Create.
4. Enter a template name.
5. Click the Save button.

You will now see the default template markup in the backoffice template editor.

Created template

Templates are registered in the Umbraco database, so adding a .cshtml file to the Views folder does not create one on its own.

If the file already exists, create the Template using the file name as the alias. Umbraco picks up the existing file content instead of overwriting it.

Allowing a Template on a Document Type

To use a Template on your content, you must first allow it on the content Document Type.

1. Open the Document Type you want to use the template.
2. Open the Templates Workspace View.
3. Select your Template under the Allowed Templates section.

Allowing template

Inheriting a Template

A Template can inherit content from a "Master Template". This is done by using the ASP.NET views Layout feature.

Let's say you have a Template called MainView, containing the following HTML:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
    Layout = null;
}
<!DOCTYPE html>
<html lang="en">
    <body>
        <h1>Hello world</h1>
        @RenderBody()
    </body>
</html>

This file contains the structural HTML tags for your website.

By using the Template as the "Master Template" on your other Templates, you can ensure that they inherit the same structural HTML.

Follow these steps to use a Template file as a Master Template:

1. Open one of your Template files.
2. Select the Master template: No master button above the editor.
3. Select the Template that should be defined as the Master Template.
4. Click Choose.

Inherit template

Alternatively, you can manually change the value of the Layout variable in the Template using the name of the Template file.

The updated markup will look something like the snippet below and the Template is now referred to as a Child Template:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
    Layout = "MainView.cshtml";
}
<p>My content</p>

When a page that uses a Template with a Master Template defined is rendered, the HTML of the two templates is merged.

The code from the Template replaces the @RenderBody() tag in the Master Template. Following the examples above, the final HTML will look like the code in the snippet below:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
    Layout = null;
}
<!DOCTYPE html>
<html lang="en">
    <body>
        <h1>Hello world</h1>
        <p>My content</p>
    </body>
</html>

Named Sections

Template Sections give you added flexibility when building your templates. Use the Template Section together with a Master Template setup, to decide where sections of content are placed.

If a Child Template needs to add code to the <head> tag a Section must be defined and then used in the Master Template. This is made possible by Named Sections.

Using code

Define a named section in your Template:

@section SectionName {
    
}

Add your code between the curly brackets, then render the section in your Master Template:

@RenderSection("SectionName", false)

For instance, if you want to be able to add HTML to your <head> tags, you would add the tag there:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
    Layout = null;
}

<html>
    <head>
        <title>Title</title>
        @RenderSection("SectionName", false)
    </head>

    <body>
    </body>
</html>

Using the backoffice

The Sections dialog writes the same @section and @RenderSection() code for you:

1. Open your Template.
2. Select the Sections option.
3. Choose Define a named section.
4. Give the section a name and click Submit.

Define a named section by giving it a name

1. Add your code between the curly brackets.
2. Save the changes.
3. Open the Master Template.
4. Choose a spot for the section and set the cursor there.
5. Select the Sections option.
6. Choose Render a named section.
7. Enter the name of the section you want to add.
8. Click Submit.

Making a section mandatory

Making a section mandatory means that any template using the Master Template is required to have the section defined.

Keep in mind that whenever a mandatory named section is missing, it will result in errors on your website.

To make the section mandatory, you have two options:

• Pass true as the second argument: @RenderSection("SectionName", true).
• Check the Section is mandatory field when using the Sections dialog in the backoffice.

Create partial

Injecting Partial Views

Another way to reuse HTML is to use partial views - which are small reusable views that can be injected into another view.

Like Templates, a partial view is a .cshtml file in your project, stored in the Views/Partials folder. You can also create one from the Partial Views folder in the backoffice. For more information, see Partial Views.

Create partial

The partial view can be injected into any template using the <partial> tag helper, like so:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
    Layout = "MasterView.cshtml";
}

<h1>My new page</h1>
<partial name="~/Views/Partials/a-new-view.cshtml" />

Related Articles

• Working with MVC
• Rendering content
• Partial Views

Tutorials

• Creating a basic website with Umbraco