How to work with MVC templates in Umbraco

Views

Working with MVC Views and Razor syntax in Umbraco

See some quick examples here

Partial Views

Documentation covering how to use Partial Views. This is not documentation about using "Partial View Macros", this documentation relates to using native MVC partial views within Umbraco.

Child Actions

Using MVC Child Actions in Umbraco

ViewComponents

Using MVC Child Actions in Umbraco

Querying

How to query for published data in your Views

Working with MVC Views and Razor syntax in Umbraco

Properties available in Views

All Umbraco views inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.NameOfYourDocType> along with the using statement @using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;. This exposes many properties that are available in razor. The properties on the Document Type can be accessed in a number of ways:

• @Model (of type Umbraco.Web.Mvc.ContentModel) -> the model for the view which contains the standard list of IPublishedContent properties but also gives you access to the typed current page (of type whatever type you have added in the angled brackets).

• @Umbraco (of type UmbracoHelper) -> contains many helpful methods, from rendering macros and fields to retrieving content based on an Id and tons of other helpful methods. See UmbracoHelper Documentation

• @Html (of type HtmlHelper) -> the same HtmlHelper you know and love from Microsoft but we've added a bunch of handy extension methods like @Html.BeginUmbracoForm

• @UmbracoContext (of type Umbraco.Cms.Web.Common.UmbracoContext)

Rendering a field in a strongly typed view

This is probably the most used method which renders the contents of a field using the alias of the content item.

@Model.Value("bodyContent")

If you're using the method from within a partial view then be aware that you will need to inherit the context so the method knows which type to get the desired value from. You'd do this at the top of partial view and so strongly typed properties can then be accessed in the partial view. For instance you can pass "HomePage" like this:

@inherits UmbracoViewPage<HomePage>
...
@Model.Value("title")

You will also need to pass the "Context" to the @Model.Value() method if you're looping over a selection like this where we pass the "item" variable.

Looping over a selection works in a similar way. If you have a property that contains, for instance, an IEnumberable collection, you can access the individual items using a foreach loop. Below illustrates how you might do that using "item" as a variable.

@{
    var collection = Model.ItemList;
}

<ul>
    @foreach(var item in collection)
    {
        <p>@item.Name</p>
    }
</ul>

If you want to convert a type and it's possible, you can do that by typing a variable and assigning the value from your property to it. This could look like the example below.

@foreach (TeamMember person in Model.TeamMembers)
{
    <a href="@person.Url()">
       <p>@person.Name</p>
    </a>
}

In this example, we are looping through a list of items with the custom made type TeamMember assigned. This means we are able to access the strongly typed properties on the TeamMember item.

Rendering Macros

Rendering a macro is done using UmbracoHelper. There are 3 overloads, we'll start with the most basic:

This renders a macro with the specified alias without any parameters:

@await Umbraco.RenderMacroAsync("myMacroAlias")

This renders a macro with some parameters using an anonymous object:

@await Umbraco.RenderMacroAsync("myMacroAlias", new { name = "Ned", age = 28 })

This renders a macro with some parameters using a dictionary

@await Umbraco.RenderMacroAsync("myMacroAlias", new Dictionary<string, object> {{ "name", "Ned"}, { "age", 27}})

UmbracoHelper Documentation

Accessing Member data

IMemberManager is the gateway to everything related to members when templating your site. IMemberManager Documentation

@using Umbraco.Cms.Core.Security;
@inject IMemberManager _memberManager;

@if(_memberManager.IsLoggedIn())
{
    <p>A Member is logged in</p>
}
else
{
    <p>No member is logged in</p>
}

Models Builder

Models Builder allows you to use strongly typed models in your views. Properties created on your document types can be accessed with this syntax:

@Model.BodyText

When Models Builder resolve your properties it will also try to use value converters to convert the values of your data into more convenient models. This allows you to access nested objects as strong types instead of having to rely on dynamics and risking having a lot of potential errors when working with these.

Models Builder documentation

This section will show you how to use MVC Partial Views in Umbraco. Please note, this is documentation relating to the use of native MVC partial views, not 'Partial View Macros'

Overview

Using Partial Views in Umbraco is exactly the same as using Partial Views in a normal MVC project. There is detailed documentation on the Internet about creating and using MVC partial views

Partial views allow you to re-use components between your views (templates).

View Locations

The locations to store Partial Views when rendering in the Umbraco pipeline is:

~/Views/Partials

The standard MVC partial view locations will also work:

~/Views/Shared
~/Views/Render

The ~/Views/Render location is valid because the controller that performs the rendering in the Umbraco codebase is the: Umbraco.Cms.Web.Common.Controllers.RenderController

If however you are Hijacking an Umbraco route and specifying your own controller to do the execution, then your partial view location can also be:

~/Views/{YourControllerName}

Example

A quick example of a content item that has a template that renders out a partial view template for each of its child documents:

The MVC template markup for the document:

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

<html>
<body>
@foreach(var page in Model.Children().Where(x => x.IsVisible()))
    {
        <div>
            @Html.Partial("ChildItem", page)
        </div>
    }
</body>
</html>

The partial view (located at: ~/Views/Partials/ChildItem.cshtml)

@model IPublishedContent
<strong>@Model.Name</strong>

Strongly typed Partial Views

Normally you would create a partial view by using the @model MyModel syntax. However, inside of Umbraco you will probably want to have access to the handy properties available on your normal Umbraco views like the Umbraco helper: @Umbraco and the Umbraco context: @UmbracoContext. The good news is that this is possible. Instead of using the @model MyModel syntax, you need to inherit from the correct view class, so do this instead:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<MyModel>

By inheriting from this view, you'll have instant access to those handy properties and have your view created with a strongly typed custom model.

Another case you might have is that you want your Partial View to be strongly typed with the same model type (IPublishedContent) as a normal template if you are passing around instances of IPublishedContent. To do this, have your partial view inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage (like your normal templates). When you render your partial, a neat trick is that you can pass it an instance of IPublishedContent. For example:

@foreach(var child in Model.Children())
{
    @Html.Partial("MyPartialName", child)
}

Caching

You don't normally need to cache the output of Partial views, like you don't normally need to cache the output of User Controls, but there are times when this is necessary. Like macro caching, we provide caching output of partial views. This is done by using an HtmlHelper extension method:

@await Html.CachedPartialAsync("ChildItem", page, TimeSpan.FromHours(1))

The above will cache the output of your partial view for one hour when not running Umbraco in debug mode. Additionally, there are a few optional parameters you can specify to this method. Here is the full method signature:

Task<IHtmlContent?> CachedPartialAsync(
        this IHtmlHelper htmlHelper,
        string partialViewName,
        object model,
        TimeSpan cacheTimeout,
        bool cacheByPage = false,
        bool cacheByMember = false,
        ViewDataDictionary? viewData = null,
        Func<object, ViewDataDictionary?, string>? contextualKeyBuilder = null)

So you can specify to cache by member and/or by page and also specify additional view data to your partial view. * However*, if your view data is dynamic (meaning it could change per page request) the cached output will still be returned. This same principle applies if the model you are passing in is dynamic. Please be aware of this: if you have a different model or viewData for any page request, the result will be the cached result of the first execution. If this is not desired you can generate your own cache key to differentiate cache instances using the contextualKeyBuilder parameter

To create multiple versions based on one or more viewData parameters you can do something like this:

@await Html.CachedPartialAsync("ChildItem", Model, TimeSpan.FromHours(1), true, false, new ViewDataDictionary(ViewData)
{
    { "year", Context.Request.Query["year"] }
}, (model, viewData) => viewData?["year"] + viewData?["Parameter2"]?.ToString() )

Or using a custom helper function:

@functions{
    private static Func<object, ViewDataDictionary?, string>? CacheBy(params string[] keys)
    {
        return (model, viewData) => String.Join("", keys.Select(s => viewData?[s]?.ToString() ?? string.Empty));
    }
}

@await Html.CachedPartialAsync("MediaGallery", Model, TimeSpan.FromHours(1), true, false, new ViewDataDictionary(ViewData)
        {
            { "year", Context.Request.Query["year"] }
        }, CacheBy("year", "Parameter2"))

Or even based on a property on the Model (though if Model is the current page then cacheByPage should be used instead):

 @await Html.CachedPartialAsync("MediaGallery", Model, TimeSpan.FromHours(1), true, false, new ViewDataDictionary(ViewData) { },
 (model, viewData) => (model is IPublishedContent pc ? pc.Name : null) ?? string.Empty)

Regardless of the complexity here the contextualKeyBuilder function needs to return a single string value.

Caching is only enabled when your application has debug="false". When debug="true" caching is disabled. Also, the cache of all CachedPartials is emptied on Umbraco publish events.

In the previous versions of MVC, we used Child Actions to build reusable components/widgets consisting of both Razor markup and backend logic. The backend logic was implemented as a controller action and marked with a [ChildActionOnly] attribute. Child Actions are no longer supported in ASP.NET Core MVC. Instead, we will use the View Component feature.

View Component Overview

View components replace the traditional Controller (SurfaceController)/Partial View relationship and instead offers a modular approach of separating your views in to several smaller units. View Components are self-contained objects that consistently render HTML from a Razor view.

View components are:

• Generated from a C# class

• Derived from the base class ViewComponent and

• Associated with a Razor file (*.cshtml) to generate markup.

are similar to partial views but they are much more powerful compared to the partial views. View components do not use model binding, instead they work with the data provided when calling it.

View Components can be implemented in any part of the web application where there are some possibilities to duplicate code like Header, Navigation Pane, Login Panel, Menu, Shopping Cart, Footer, BlockList Items and so on. View Components behave like a web part containing both business logic and UI design to create a package which can be reused in multiple parts of the web application.

A view component code consists of two parts:

• The View Component class derived from the ViewComponent class:

• Returns a Task object as IViewComponentResult:

Create a class for a ViewComponent

In this example, let's create a ViewComponent for a Product List and render it on the HomePage of the website.

Create a folder named ProductView. In this folder, create a new class named ProductViewViewComponent.cs as below:

Create a View for ViewComponent

In Views folder, create new folders at Views\Shared\Components\ProductView. In the ProductView folder, create a new file named Default.cshtml as below:

UmbracoHelper in a ViewComponent

Adding the following declaration will give access to the UmbracoHelper object inside the ViewComponent View

Invoking a View Component

You can invoke a ViewComponent from anywhere (even from within a Controller or another ViewComponent). Since this is our Product List, we want it rendered on the Home page - so we’ll invoke it from our HomePage.cshtml file using:

View Component Locations

By default, the framework searches for the Component View path in the following areas:

• /Views/{Controller Name Folder}/Components/{View Component Name Folder}/{View Name}

• /Views/Shared/Components/{View Component Name Folder}/{View Name}

Lots of examples of using various techniques to render data in a view

Rendering the raw value of a field from IPublishedContent

Rendering the converted value of a field from IPublishedContent

Rendering a macro

Rendering a macro with parameters using an anonymous object

Rendering a macro with parameters using a dictionary

Rendering some member data

This section will describe how you can render content from other nodes besides the current page in your MVC Views

Querying for content and media by id

The easiest way to get some content by Id is to use the following syntax (where 1234 is the content id you'd like to query for):

You can also query for multiple content items using multiple ids:

This syntax will support an unlimited number of Ids passed to the method.

You can also retrieve content using the Guid Id. In the example "ca4249ed-2b23-4337-b522-63cabe5587d1" is the key of the content.

You can also pass a to retrieve the content.

The same query structures apply to media:

Traversing

All of these extension methods are available on Umbraco.Core.Models.IPublishedContent so you can have strongly typed access to all of them with intellisense for both content and media. The following methods return IEnumerable<IPublishedContent>

Additionally there are other methods that will return a single IPublishedContent

Complex querying (Where)

With the IPublishedContent model we support strongly typed LINQ queries out of the box so you will have intellisense for that.

Some examples

Where children are visible

Traverse for sitemap

Content sub menu

Complex query

With the strongly typed IPublishedContent you can do complex queries.

Creating an HTML form to submit data with MVC in Umbraco is possible in a few steps.

If you want to create a Form:

1. Using view models, views, controllers, and a handy HtmlHelper extension method called BeginUmbracoForm, see the article.

2. Using Umbraco Forms, see the article.