Templates

Creating, managing, and reusing templates in Umbraco.

Rendering content

Querying and rendering published content.

Rendering media

Querying and rendering media items.

Partial Views

Working with partial views in Umbraco's templates.

Partial View Macro Files

Working with partial views macro files.

Stylesheets and JavaScript

Working with CSS and JavaScript in Umbraco's templates.

The Razor Cheatsheet is a collection of common methods used for building templates and views in Umbraco CMS.

Get the Umbraco 11 Cheatsheet: https://umbra.co/razorCheatsheet

You can also find the cheatsheet on GitHub where you can give feedback, contribute, or download the template used to generate the sheet.

Use the cheatsheet if you:

• Use Models Builder on your project and

• Use Umbraco 11.

Shows how to perform common logical tasks in Razor like if/else, foreach loops, switch statements and using the @ character to separate code and markup.

The @ symbol

The @ symbol is used in Razor to initiate code, and tell the compiler where to start interpreting code, instead of returning the content of the file as text. Using a single character for this separation, results in cleaner, compact code which is easier to read.

@* Writing a value inside a html element *@

<p>@Model.Name</p>

@* Inside an attribute *@
<a href="@Model.Url()">@Model.Name</a>

@* Using it to start logical structures *@
@if (selection?.Length > 0)
{
    <ul>
        @foreach (var item in selection)
        {
            <li>
                <a href="@item.Url(PublishedUrlProvider)">@item.Name</a>
            </li>
        }
    </ul>
}

Embedding comments in razor

Commenting your code is important, use comments to explain what the code does. @* *@ indicates a comment, which will not be visible in the rendered output.

@* Here we check if the name is equal to foobar *@
@if (Model.Name == "foobar")
{
    @foreach (var child in Model.Children)
    {
        @* here we write stuff for each child page *@
        <p>write stuff</p>
    }
}

If/else

If/else statements perform one task if a condition is true, and another if the condition is not true

@if (Model.Name == "home")
{
    <p>This is the homepage!</p>
}

@if (Model.NodeTypeAlias == "TextPage")
{
    <p>This is a textpage</p>
}
else
{
    <p>This is NOT a textpage</p>
}

Foreach loops

A foreach loop goes through a collection of items, typically a collection of pages and performs an action for each item

@foreach (var item in Model.Children)
{
    <p>The item name is: @Item.Name</p>
}

Switch block

A Switch block is used when testing a large number of conditions

@switch (Model.WeekDay)
{
    case "Monday":
        "<p>It is Monday</p>";
        break;
    case "Tuesday":
        "<p>It is Tuesday</p>";
        break;
    case "Wednesday":
        "<p>It is Wednesday</p>";
        break;
    default:
        "<p>It's some day of the week</p>";
        break;
}

More information

• More examples

• Querying

Template sections support the ability to add additional Named Sections to layout templates. These sections can be defined anywhere in the layout file (including within the section of the HTML) and allow you to output dynamic content in your template.

Defining a Named Section

You can define a part of your template as a named section by wrapping it in @section. This can be rendered in a specific area of the parent of this template, by using @RenderSection.

For example, you can define the following section within a child template like a Content page:

@section Contact
{
    <div class="container">
        <div class="row section">
            <div class="col-md-9">
                <p>@Model.AuthorName()</p> 
            </div>
        </div>
    </div>

}

To define a Named Section, follow these steps:

1. Go to Settings.

2. Navigate to a template and click Sections.
3. Select Define a named section and enter the Section Name.
4. Click Submit.

Render a Name Section

Renders a named area of a child template, by inserting a @RenderSection(name) placeholder. This renders an area of a child template that is wrapped in a corresponding @section [name] definition.

For example, you can define the following section within a Master template:

@RenderSection("Contact", false)

To render a Named Section, follow these steps:

1. Go to Settings.

2. Navigate to a template and click Sections.
3. Select Render a named section and enter the Section Name.
4. [Optional] Select Section is mandatory. This means that the child templates need to have the named section defined for them to work.

5. Click Submit.

The primary task of any template is to render the values of the current page or the result of a query against the content cache.

Display a value in your template view

Each property in your has an alias, this is used to specify where in the template view to display the value.

Specifying types of data

You can specify the type of data being returned to help you format the value for display, consider the publish date in our example:

To use the <IHtmlContent> as the data return type, add the @using Microsoft.AspNetCore.Html; directive.

Using ModelsBuilder

Working with the grid

Using fall-back methods

The .Value() method has a number of optional parameters that support scenarios where we want to "fall-back" to some other content.

To use the fallback type, add the @using Umbraco.Cms.Core.Models.PublishedContent; directive.

• To display a static, default value when a property value is not populated on the current content item:
• A second supported method is to traverse up the tree ancestors to try to find a value. If the current content item isn't populated for a property, we can retrieve the value from the parent, grand-parent, or a higher ancestor in the tree. The first ancestor encountered that has a value will be the one returned.
• If developing a multi-lingual site and fall-back languages* have been configured, the third method available is to retrieve a value for a different language, if the language we are requesting does not have content populated. In this way, we could render a field containing French content for a property if it's populated in that language, and if not, default to English.
• We can also combine these options to create some more sophisticated scenarios. For example, we might want to fall-back via language first, and if that doesn't find any populated content, then try to find a value by traversing through the ancestors of the tree. We can do that using the following syntax, with the order of the fall-back options provided determining the order that content will be attempted to be retrieved:
• In this example, we are looking for content firstly on the current node for the default language, and if not found we'll search through the ancestors. If failing to find any populated value from them, we'll use the provided default:
• We can use similar overloads when working with ModelsBuilder, for example:

  • Fall-back languages can be configured via the Languages tree within the Settings section.

  • Each language can optionally be provided with a fall-back language, that will be used when content is not populated for the language requested and the appropriate overload parameters are provided.

  • It is possible to chain these language fall-backs, so requesting content for Portuguese, could fall-back to Spanish and then on to English.

Query content

You can do this by querying content relative to your current page in template views:

More information

A Partial View (.cshtml file) is a regular view that can be used multiple times throughout your site. A Partial View is used to break up large markup files into smaller components such as header, footer, navigation menu, etc. It helps to reduce the duplication of code. A partial view renders a view within the parent view.

Partial Views in the Backoffice

You can create and edit partial views in the Partial Views folder from the Settings section of the Backoffice.

In the Create menu, there are three options available:

• New empty partial view

• New partial view from snippet

• Folder (for keeping the partial views organized)

Creating a Partial View

To create a partial view, go to the Settings section in the Umbraco backoffice and right-click the Partial Views folder. Choose Create. Select New empty partial view and enter a partial view name and click the Save button. You will now see the partial view markup in the backoffice editor.

By default, the partial view is saved in the Views/Partials folder in the solution.

Creating a Partial View from Snippet

To create a partial view from the snippet, go to the Settings section in the Umbraco backoffice and right-click the Partial Views folder. Choose Create. Select New empty partial view from snippet. Select the snippet you want to create a partial view for and enter a partial view name. The code snippet you selected is displayed in the backoffice editor. Click the Save button.

By default, the partial view is saved in the Views/Partials folder in the solution. Umbraco provides the following partial view snippets:

• Empty - Creates an empty partial view file.

• Breadcrumb - Creates a breadcrumb of parents using the Ancestors() method to generate links in an unordered HTML list. It displays the name of the current page without a link.

• Edit Profile - Creates a Member profile model that can be edited.

• List Ancestors From Current Page - Displays a list of links to the parents of the current page using the Ancestors() method to generate links in an unordered HTML list. It displays the name of the current page without a link.

• List Child Pages From Current Page - Displays a list of links to the children of the current page using the Children() method to generate links in an unordered HTML list.

• List Child Pages Ordered By Date - Displays a list of links to the children of the current page using the Children() method to generate links in an unordered HTML list. The pages are sorted by the creation date in a descending order using the OrderByDescending() method.

• List Child Pages Ordered By Name - Displays a list of links to the children of the current page using the Children() method to generate links in an unordered HTML list. The pages are sorted by the page name using the OrderBy() method.

• List Child Pages With DocType - Displays only the children of a certain Document Type.

• List Descendants From Current Page - Displays a list of links for every page below the current page in an unordered HTML list.

• Login - Displays a login form.

• Login Status - Displays the user name if the user is logged in.

• Multinode Tree-picker - Lists the items from a Multinode tree picker using the picker's default settings.

• Navigation - Displays a list of links of the pages under the top-most page in the Content tree. It also highlights the currently active page/section in the navigation menu.

• Register Member - Displays a Member registration form. It will only display the properties marked as Member can edit on the Info tab of the Member Type.

• Site Map - Displays a list of links of all the visible pages of the site using the Traverse() method to select and display the markup and links as nested unordered HTML lists.

Creating a Folder

To create a folder, go to the Settings section in the Umbraco backoffice and right-click the Partial Views folder. Choose Create. Select Folder. Enter a folder name and click the Create button.

Rendering a Partial View

To render the created partial view into any template, use any of these helper methods: @Html.PartialAsync, @Html.Partial(), or @Html.RenderPartial()

Related Articles

Video Materials

Stylesheets in the Backoffice

You can create and edit stylesheets in the Stylesheets folder in the Settings section of the Backoffice.

In the Create menu, these options are available:

• Stylesheet file (for use in templates/views)

• Folder (for keeping stylesheets organized)

After creating a new stylesheet, you would work with it as you would with templates or JavaScript files - using the built-in backoffice text editor. When you're working with stylesheets, you also have access to the Rich Text Editor, which allows you to create CSS styles and get a real-time preview.

The rules you create in the Rich Text Editor section will carry over to the Code tab.

To reference your newly included stylesheet in a template file, navigate to Templates, pick the template you like (css files are usually referenced in the layout or home templates) and link to it with the link tag.

By default, the stylesheets will be saved in the wwwroot/css folder in the solution. To reference them you can use either of the methods used in the above screenshot.

or

With the stylesheet referenced, you will be able to style the template file with the rules and classes defined in the stylesheet.

JavaScript files in the Backoffice

To create and edit JavaScript files in the Backoffice, head on over to the Scripts folder in the Settings section of the Backoffice.

From here you can add a new JavaScript file, or a new folder.

Add a new JavaScript file and write your code:

Then, navigate to the template where you would like to include your JS file.

By default all JavaScript files will be stored in the wwwroot/scripts folder in the solution.

Bundling & Minification for JavaScript and CSS

You can use whichever tool you are comfortable with for bundling & minification by implementing the IRuntimeMinifier interface in your custom minifier class, though it is worth noting that Umbraco 9+ ships with Smidge which offers lightweight runtime bundling and minification.

You can create various bundles of your site's CSS or JavaScript files in your code that can be rendered later in your views. There can be a single bundle for the entire site, or a common bundle for the files you want to be loaded on every page, as well as page-specific bundles, just by listing your resources in the order you like.

Step 1: Create a INotificationHandler<UmbracoApplicationStartingNotification>

Step 2: Register the INotificationHandler in the Program.cs file.

Step 3: Render the bundles by the bundle name in a view template file using the Smidge TagHelper:

Bundling Options

The following bundling options can be set when creating your bundles:

Rendering

Using Smidge TagHelper

Using IRuntimeMinifier

Templating in Umbraco builds on the concept of Razor Views from ASP.NET MVC - if you already know this, then you are ready to create your first template - if not, this is a quick and handy guide.

Creating your first Template

By default, all document types should have a template attached - but in case you need an alternative template or a new one, you can create one:

Open the Settings section inside the Umbraco backoffice and right-click the Templates folder. Choose Create. Enter a template name and click the Save button. You will now see the default template markup in the backoffice template editor.

Allowing a Template on a Document Type

To use a template on a document, you must first allow it on the content's type. Open the Document Type you want to use the template, go to the Templates tab and select the template under the Allowed Templates section.

Inheriting a Master Template

A template can inherit content from a master template by using the ASP.NET views Layout feature. Let's say we have a template called MasterView, containing the following HTML:

We then create a new template called textpage and in the template editor, click on the Master Template button and set its master template to the template called MasterView:

This changes the Layoutvalue in the template markup, so textpage looks like this:

When a page using the textpage template renders, the final HTML will be merged replacing the @renderBody() placeholder, and produce the following:

Template Sections

What's good to know, is that you are not limited to a single section. Template sections allow child templates that inherit the master layout template to insert HTML code up into the main layout template. For example, a child template inserting code into the <head> tag of the master template.

For instance, if you want to be able to add HTML to your <head> tags write:

By default, when rendering a named section, the section is not mandatory. To make the section mandatory, add true or enable Section is mandatory field in the Sections option.

On your child page template call @section Head {} and then type your markup that will be pushed into the Master Template:

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, create a partial view, by right-clicking Partial Views and selecting Create. You can then either create an empty partial view or create a partial view from a snippet.

The created partial view can now be injected into any template by using the @Html.Partial() method like so:

Related Articles

Tutorials

Umbraco Learning Base

Partial View Macro Files

A Macro is a reusable piece of functionality with some configuration options in the Backoffice. A Partial View Macro File (.cshtml file) is a specific file configuration that is associated with the Macro. A Partial View Macro File generates a Macro that can be inserted and rendered in the Grid and Rich Text Editor data types. Additionally, you can define parameter values and enable caching in Macros in the Backoffice. Partial View Macro Files are the recommended macro type to use in Umbraco.

Partial View Macro Files in the Backoffice

You can create and edit Partial View Macro Files in the Partial View Macro Files folder from the Settings section of the Backoffice.

In the Create menu, there are four options available:

• New partial view macro

• New partial view macro (without macro)

• New partial view macro from snippet

• Folder (for keeping the partial view macro files organized)

Creating a Partial View Macro File

To create a Partial View Macro File, go to the Settings section in the Umbraco backoffice and right-click the Partial View Macro Files folder. Choose Create. Select New partial view macro and enter a Partial View Macro Filename. Enter the macro logic and click the Save button. You will now see the Partial View Macro File in the Partial View Macro Files folder. You also see the macro in the Macros folder in the Backoffice.

By default, the Partial View Macro File is saved in the Views/MacroPartials folder.

Creating a Partial View Macro File (without macro)

To create a Partial View Macro File without a macro, go to the Settings section in the Umbraco backoffice. Click right on the Partial View Macro Files folder. Choose Create. Select New partial view macro (without macro) and enter a Partial View Macro Filename. Enter the macro logic and click the Save button. You will now see only the Partial View Macro File in the Partial View Macro Files folder in the Backoffice.

By default, the Partial View Macro File is saved in the Views/MacroPartials folder.

Creating a Partial View Macro File from Snippet

To create a Partial View Macro File from the snippet, go to the Settings section in the Umbraco backoffice. Click right on the Partial Views Macro Files folder. Choose Create. Select New empty partial view macro from snippet. Select the snippet you want to create a partial view for and enter a Partial View Macro Filename. The code snippet you selected is displayed in the backoffice editor. Click the Save button. You will now see the Partial View Macro File in the Partial View Macro Files folder. You also see the macro in the Macros folder in the Backoffice.

By default, the partial view is saved in the Views/MacroPartials folder. Umbraco provides the following partial view macro snippets:

• Empty - Creates an empty partial view file.

• Breadcrumb - Creates a breadcrumb of parents using the Ancestors() method to generate links in an unordered HTML list. It displays the name of the current page without a link.

• Edit Profile - Creates a Member profile model that can be edited.

• Gallery - Displays a gallery of images from the Media section. It works with either a 'Single Media Picker' or a 'Multiple Media Picker' macro parameters.

• List Ancestors From Current Page - Displays a list of links to the parents of the current page using the Ancestors() method to generate links in an unordered HTML list. It displays the name of the current page without a link.

• List Child Pages From Changeable Source - Lists all the child pages under a specific page in the Content tree.

• List Child Pages From Current Page - Displays a list of links to the children of the current page using the Children() method to generate links in an unordered HTML list.

• List Child Pages Ordered By Date - Displays a list of links to the children of the current page using the Children() method to generate links in an unordered HTML list. The pages are sorted by the creation date in a descending order using the OrderByDescending() method.

• List Child Pages Ordered By Name - Displays a list of links to the children of the current page using the Children() method to generate links in an unordered HTML list. The pages are sorted by the page name using the OrderBy() method.

• List Child Pages With DocType - Displays only the children of a certain Document Type.

• List Descendants From Current Page - Displays a list of links for every page below the current page in an unordered HTML list.

• List Images From Media Picker - Displays a series of images from a media folder.

• Login - Displays a login form.

• Login Status - Displays the user name if the user is logged in.

• Multinode Tree-picker - Lists the items from a Multinode tree picker using the picker's default settings.

• Navigation - Displays a list of links of the pages under the top-most page in the Content tree. It also highlights the currently active page/section in the navigation menu.

• Register Member - Displays a Member registration form. It will only display the properties marked as Member can edit on the Info tab of the Member Type.

• Site Map - Displays a list of links of all the visible pages of the site using the Traverse() method to select and display the markup and links as nested unordered HTML lists.

• InsertUmbracoFormWithTheme - If a theme is provided as a macro parameter, Umbraco Forms will use the custom theme files.

• RenderUmbracoFormScripts - Renders your Umbraco Forms scripts. In many cases, you might prefer rendering your scripts at the bottom of the page as this generally improves site performance.

Creating a Folder

To create a folder, go to the Settings section in the Umbraco backoffice and right-click the Partial Views Macro Files folder. Choose Create and select Folder. Enter a folder name and click the Create button.

Rendering a Partial View Macro File

To render the created Partial View Macro File in any template, use the RenderMacroAsync method:

Related Articles

Templates (Views) can access items in the Media library to assist in displaying rich content like galleries.

In the following examples, we will be looking at rendering an Image.

Image is only one of the 'types' of Media in Umbraco. The same principles apply to all Media Types. The properties available to render will be different from Media Type to Media Type. For example, a File will not have a Width property.

Rendering a media item

A media item is not only a reference to a static file. Like content, it is a collection of fields, such as width, height, and file path. This means that accessing and rendering media in a Template is similar to rendering content.

Example 1: Accessing a Media Image IPublishedContent item based on the ID

An uploaded image in the Media library is based on the Media Type Image which has a number of standard properties:

• Name

• Width & Height

• Size

• Type (based on file extension)

• UmbracoFile (the path to the file or JSON data containing crop information)

These standard properties are pre-populated and set during the upload process. For example, this means that the width and height are calculated for you.

If you want to add further properties to use with your Media Item, edit the Image Media Type under Settings. In this example, we are going to retrieve an image from the Media section. Then we will render out an img tag using the URL of the media item and use the Name as the value for the alt attribute.

@{
    // The Umbraco Helper has a Media method that will retrieve a Media Item by Guid in the form of IPublishedContent. In this example, the Media Item has a Guid of 55240594-b265-4fc2-b1c1-feffc5cf9571

    var mediaItem = Umbraco.Media(Guid.Parse("55240594-b265-4fc2-b1c1-feffc5cf9571"));

    if (mediaItem != null)
    {
        // To get the URL for your media item, you use the Url method:
        var url = mediaItem.Url();
        // to read a property by alias
        var imageHeight = mediaItem.Value<int>("umbracoHeight");
        var imageWidth = mediaItem.Value<int>("umbracoWidth");
        var orientationCssClass = imageWidth > imageHeight ? "img-landscape" : "img-portrait";

        <img src="@url" alt="@mediaItem.Name" class="@orientationCssClass"/>
    }
}

But wait a second, Umbraco comes with Models Builder. This means that you can use strongly typed models for your media items if Models Builder is enabled (which it is by default).

Example 2: Accessing a Media Image ModelsBuilder item based on the ID

As with example one, we are accessing a MediaType image using the same Guid assumption.

@{
    // Since the Image Model generated by Modelsbuilder is a compatible type to IPublishedContent we can use the 'as' operator to convert it into the ModelsBuilder Umbraco.Cms.Web.Common.PublishedModels.Image class
    var mediaItemAsImage = Umbraco.Media(Guid.Parse("55240594-b265-4fc2-b1c1-feffc5cf9571")) as Image;
    if (mediaItemAsImage != null)
    {
        // you could add this as an extension method to the Umbraco.Cms.Web.Common.PublishedModels.Image class
        var orientationCssClass = mediaItemAsImage.UmbracoWidth > mediaItemAsImage.UmbracoHeight ? "img-landscape" : "img-portrait";

        <img src="@mediaItemAsImage.Url()" alt="@mediaItemAsImage.Name" class="@orientationCssClass"/>
    }
}

Other Media Items such as File

Accessing other media items can be performed in the same way. The techniques are not limited to the Image type, but it is one of the most common use cases.

Image Cropper

The Image Cropper can be used with Image Media Types and is the default option for the umbracoFile property on an Image Media Type.

When working with the Image Cropper for an image the GetCropUrl extension method is used to retrieve cropped versions of the image. Details of the Image Cropper property editor and other examples of using it can be found in the Image Cropper article. The following is an example to help you get started with the Image Cropper.

Example of using Image Cropper

@{
    var mediaItemToCrop = Umbraco.Media(Guid.Parse("55240594-b265-4fc2-b1c1-feffc5cf9571"));
    if (mediaItemToCrop != null)
    {
        <img src="@Url.GetCropUrl(mediaItemToCrop, "square")" alt="@mediaItemToCrop.Name"/>
    }
}

This example assumes that you have set up a crop called square on your Image Cropper Data Type.

If you want the original, uncropped image, you can ignore the GetCropUrl extension method and use one of the previously discussed approaches as shown below.

<img src="@mediaItemToCrop.Url()" />

More information

• Media Picker

• Image Cropper

• Creating a Media Type