Models Builder can be used in different modes:

• InMemory models

• SourceCode models

The mode is indicated by the Umbraco:CMS:ModelsBuilder:ModelsMode key in the configuration (appsettings.json files).

In memory

Corresponds to the InMemoryAuto setting value.

With InMemory models, models are generated and compiled on the fly, in memory, at runtime. They are available in views exclusively.

This is for a setup that exclusively uses the Umbraco backoffice, and do not use custom code such as controllers. Whenever a content type is modified, models are updated without restarting Umbraco (in the same way .cshtml views are recompiled).

Generation can fail for various reasons, in which case Umbraco will run without models (and front-end views fail to render). Umbraco's log file should contain all details about what prevented the generation, but it is probably faster to check the Models Builder dashboard, which should report the last error that was encountered, if any.

Models Builder maintains some files in ~/umbraco/Data/TEMP/InMemoryAuto:

• models.generated.cs contains the generated models code

• all.generated.cs contains the compiled code (models merged with non-generated files)

• models.hash contains a hash code of the content types

• all.dll.path contains the path to the compiled DLL file containing all the models

• Compiled/generated.cs{GUID}.dll the dll containing all the generated models

• models.err contains the last generation error information, if any

The models.hash file is used when Umbraco restarts, to figure out whether models have changed and need to be re-generated. Otherwise, the local models.generated.cs file is reused.

SourceCode Models

Corresponds to the SourceCodeManual and SourceCodeAuto setting values.

With SourceCode models, models are generated in the ~/umbraco/models directory, and that is all. It is then up to you to decide how to compile the models (e.g. by including them in a Visual Studio solution).

Generation can fail for various reasons, in which case no models are generated. Umbraco's log file should contain all details about what prevented the generation, but it is probably faster to check the Models Builder dashboard, which should report the last error that was encountered, if any.

The modelsbuilder works much in the same way whether using SourceCodeManual or SourceCodeAuto. The only real difference between the two are that with SourceCodeManual you must manually trigger the generation of the models from the models builder dashboard, whereas with SourceCodeAuto the models are automatically generated whenever content types change.

API models and Dll Models

In this article you can learn how to create and update a Macro, as well as how to configure its parameters.

Creating macros

There are a couple of ways to create a macro.

Manually

The first way is to manually create a macro, by right-clicking the Macro folder in the Settings section:

Give it a name in the dialog screen, and you'll be presented with the macro editor.

Partial View Macro files

The second option is to create the macro through Partial View Macro Files.

The dialog provides the following options:

• New partial view macro: Will give you an empty macro with an associated empty partial view file

• New partial view macro (without macro): Will give you a partial view, without an associated macro

• New partial view macro from snippet...: Will give you the option to choose between a pre-defined set, including a macro and a partial view with a code snippet

• Folder...: Will give you the option to create a folder below "Partial View Macro Files"

Macro Editor

The macro editor view comes with a set of configuration options.

Macro partial view

Associate the macro with a partial view. This will already have been configured if you created the macro through the second option described above, where a Partial view was created along with the macro.

Editor settings

Use in rich text editor and the grid

If selected will allow an editor to insert this macro in to a Rich Text Editor and/or into a Grid editor.

Caching options

Cache period

Defines how many seconds the macro output will be cached for once it is rendered

Cache by page

If selected, then the macro will be cached based on the current page it is rendered on. This is useful if your macro has content that is dynamic to the current page it is being rendered on. If your macro's output is static (the same) no matter what page it is rendered on then it is better to not check this box.

Cache personalized

Similar to the 'Cache by page', this will cache the output of a macro based on a member that is logged in. If your macro is static (the same) no matter what member is logged in, or if your website does not have membership then it is better to not check this box.

Macro parameters

Macro parameters can be used to change the output of a macro at runtime. Macro parameters are often used as a way for your editors to change the output of a macro when they insert them into rich text editors. As an example, suppose you have a widget that displays a list of links which are children of a particular content item. You could define a macro parameter that indicates for which content item to render child links for and your editor can select this content item when inserting the macro into the rich text editor.

The macro parameter dialog looks like this:

Here you can add/modify/remove macro parameters.

Default macro parameter types

This list defines the different types of macro parameters:

• Checkbox(Umbraco.TrueFalse) - A true/false value

• Content Type picker (contentType) - Choose a type from existing Document Types

• Decimal (Umbraco.Decimal) - accepts only numbers

• Email address (Umbraco.EmailAddress) - validates to valid email addresses

• Multiple Content Picker (Umbraco.MultiNodeTreePicker) - pick 1 or more nodes from the Content tree

• Multiple Content Type Picker (contentTypeMultiple) - pick 1 or more types from existing Document Types

• Multiple Media Picker (Umbraco.MultipleMediaPicker) - pick 1 or more media items

• Multiple Property Type Picker (propertyTypePickerMultiple) - pick 1 or more from existing property types

• Multiple Tab Picker (tabPickerMultiple) - pick 1 or more from existing tabs

• Numeric (Umbraco.Integer) - accepts only numbers

• Property Type Picker (propertyTypePicker) - choose property from existing property types

• Tab picker (tabPicker) - select 1 from list of existing tabs

• Textarea (Umbraco.TextArea) - multiple lines of text

• Textbox (Umbraco.TextBox) - single line of text

• Media picker (Umbraco.MediaPicker) - select a single media item

• Content Picker (Umbraco.ContentPicker) - select a single content node from the Content tree

• Form Picker (UmbracoForms.FormsPicker) - choose from existing Umbraco Forms

• Forms Theme Picker (UmbracoForms.ThemePicker) - choose from existing Forms Themes

Enable Inline Macro

In some case you want to have the macro in the middle of a sentence.

To enable editors to add the macro inline, follow these steps:

1. Add a macro parameter called: enableInlineMacro.

2. Choose Checkbox (Umbraco.TrueFalse) as the type.

The next time you add the macro, enable the new parameter to add the macro inline.

Enable Inline Macro by default on a macro

In some cases, you want to have a checkbox that is enabled by default. This would enable you to create your own type of macro parameter that has 1 as the default value. To achieve this, create a DataEditor class anywhere in your Umbraco Project with the following definition:

    [DataEditor(
        alias: "enableInlineMacro",
        type: EditorType.MacroParameter,
        name: "Enable Inline Macro",
        view: "boolean",
        Group = "Macro Config",
        Icon = "icon-list")]
    public class EnableInlineMacro : DataEditor
    {
        public EnableInlineMacro(IDataValueEditorFactory dataValueEditorFactory)
            : base(dataValueEditorFactory)
        {
            DefaultConfiguration.Add("default", "1");
        }
    }

The Models builder is a tool that can generate a complete set of strongly-typed published content models for Umbraco. Models are available in both controllers and views.

Describes how to set up a macro, use macro parameters & configuring caching. Defines the different types of macros and provides details on the different macro engine APIs and their usage

What is a macro

A macro is 'wrapper' for a reusable piece of functionality that you can utilise in different places throughout your site.

You can use macros in your templates, like MVC Partial views - however they differ in that they can be configured to work with Parameters and Caching, that can be updated by editors via the Umbraco Backoffice. So if you allow a macro to be added to a Rich Text Editor or Grid cell, the editor, at the point of inserting the macro can supply the parameter values.

For example imagine adding an Image Gallery within a rich text editor, and at the point of insertion 'picking' the images to display.

Define the parameters

Using in a Rich Text Area

A Rich Text Editor should be enabled with macros in the toolbar to allow inserting macros.

Rich Text Area with macro toolbar option

Insert the macro into a Rich Text Area

The same implementation logic can be used in lots of different places on your site, and the editor can customise the output by choosing different parameters.

Implementing a Macro

Rendering Macros

Here's a basic method to render macros:

Rendering Macros with Parameters

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

This renders a macro with some parameters using a dictionary

Meaning of all the symbols

Request Collection

To retrieve a value from the request collection such as a query string parameter we specify it by prefixing with an "@" symbol.

To get a query string parameter with the key "productId" we would specify our parameter like this [@productId]

Document Type Property

Document type properties are specified by a leading "#" and then the alias of the document property.

To pass a property with the alias "bodyText" we would specify [#bodyText] in the parameter value.

Recursive Document Type Property

Recursive Document type properties are specified by a leading "$" and then the alias of the document property.

Umbraco resolves recursive parameters by looking at the current page for a value and then traversing up the content tree until a value with that alias is found.

Session Collection

Retrieve values from the session collection or cookies by prefixing with a "%" symbol.

To retrieve a value with the key "memberId" from the session collection we would specify our Macro parameter value as [%memberId]

Caching Macro Output

For long running macros that return the same results, caching boosts site performance, you can specify caching levels for the Macro in the backoffice.

Options are:

• Cache by Period - set the number of seconds to cache the output of the Macro for

• Cache by Page - Whether to create a different cached instance of the macro for each page (think breadcrumb - you wouldn't want the same breadcrumb on every page)

• Cache Personalized - whether to create a difference cached instance of the macro for each site visitor (if your Macro says 'Hi Niels' using the currently logged in Members name, you wouldn't want this cached to be the same for every visitor to the site, unless they were all called Niels)

Templating in Umbraco consists of 3 larger concepts, namely Templates (Views), Partials (Partial Views) and Macros (Macro Partials):

• Templates are used for the HTML layout of your pages.

• Partials can be included in your templates for shared functionality across different page templates.

• Macros can be used for reusable dynamic components that can be controlled by editors to embed functionality into the grid or rich text areas.

Templating technology

Umbraco uses ASP.Net MVC Views for implementing templates.

Describes how to work with MVC views, the razor syntax and APIs available. It also describes how to create forms, has some step-by-step guides and other advanced techniques.

Describes how to set up a macro, use macro parameters & configuring caching. Defines the different types of macros and provides details on the different macro engine APIs and their usage.

A tool that can generate a complete set of strongly-typed published content models for Umbraco. Models are available in controllers, views, anywhere. Runs either from the Umbraco UI, from the command line, or from Visual Studio.

Models Builder is a tool that can generate a complete set of strongly-typed published content models for Umbraco. By default, a slimmed down version of Models Builder is embedded with the main Umbraco distribution.

Models can be used anywhere that content is retrieved from the content cache, i.e. in MVC views, controllers, etc. In other words, when using the Models Builder, the content cache does not return IPublishedContent objects anymore, but strongly typed models, implementing IPublishedContent.

For each content, media and member type in the Umbraco setup, the generator creates a *.generated.cs file, corresponding to the type. For instance, a document type with a textstring property named Title, and a rich text editor named BodyText will look like this:

Now since this is an automatically generated file, it's a bit messy, the important part is that it has all the properties defined and strongly typed:

And:

Umbraco's content cache returns these objects natively: No need to map, convert or anything; the following code runs:

Models Builder respects the content types' inheritance tree, i.e. models inherit from each other if required, and mixins (content type compositions) are represented by interfaces.

Models Builder is a "code-after*_" solution. It only generates code from content types that already exist in Umbraco. It is not a "code-first" solution - code-first is a much more complex question.

Installing

The Models Builder is by default embedded in Umbraco. If you need more complex features than what is provided, you still need to add the full package. However, as of right now the package is not updated to be able to handle NetCore or Umbraco V9.

Documentation

At the core of the strongly typed models "experience" is the IPublishedModelFactory interface. This interface is part of the Umbraco core codebase. It is responsible for mapping the internal IPublishedContent implementations returned by the content cache, to strongly typed models. There is a default factory shipped with Umbraco and it is possible to replace this by custom implementations. When using the default factory, models do not necessarily need to be generated by Models Builder.

Partial View Macros are the recommended macro type to use in Umbraco. They work in both MVC and Webforms and use the unified query syntax that is available via the UmbracoHelper.

View/Model Type

All Partial View Macro views inherit from Umbraco.Cms.Web.Common.Macros.PartialViewMacroPage and the header of each Partial View Macro file will contain:

The model type for a Partial View Macro is Umbraco.Cms.Core.Models.PartialViewMacroModel. This contains all of the properties you need to render out content alongside some additional properties about the macro itself:

• MacroName

• MacroAlias

• MacroId

• MacroParameters

File Information

By default, Partial View Macros are stored in this folder:

~/Views/MacroPartials

However, if you are bundling up Partial View Macros as part of a package, they can also exist in this folder:

~/App_Plugins/[YourPackageName]/Views/MacroPartials

Since Partial View Macros are a normal MVC partial view, their file extension is cshtml. All Partial View Macro views inherit from the following view class:

Therefore, all files will contain the header (which is done automatically for you if creating Partial View Macros via the Umbraco backoffice):

Accessing Content

You can use @CurrentPage, @Model.Content, @Umbraco, ...

Accessing Macro Parameters

You can access the macro's parameters using the:

• MacroParameters property on the model which is of type IDictionary<string, object>:
• Typed GetParameterValue method in Umbraco.Cms.Core.Models namespace:
• Typed GetParameterValue method with the default value fallback:

The following configuration option can be set in the application settings (in the appsettings.json file):

• Umbraco.CMS.ModelsBuilder.ModelsMode determines how Models Builder generates models. Valid values are:

  • Nothing: Do not generate models.

  • InMemoryAuto(default): Generate models in a dynamic in-memory assembly.

  • SourceCodeManual: Generate models in ~/umbraco/models (but do not compile them) whenever the user clicks the "Generate models" button on the Models Builder dashboard in the Settings section.

  • SourceCodeAuto: Generate models in ~/umbraco/models (but do not compile them) anytime a content type changes.

• Umbraco.CMS.ModelsBuilder.ModelsNamespace (string, default is Umbraco.Cms.Web.Common.PublishedModels) specifies the generated models' namespace.

• Umbraco.CMS.ModelsBuilder.FlagOutOfDateModels (bool, default is true) indicates whether out-of-date models (for example after a content type or Data Type has been modified) should be flagged.

• Umbraco.CMS.ModelsBuilder.ModelsDirectory (string, default is ~/umbraco/models) indicates where to generate models and manage all files. Has to be a virtual directory (starting with ~/) below the website root (see also: AcceptUnsafeModelsDirectory below).

• Umbraco.CMS.ModelsBuilder.AcceptUnsafeModelsDirectory (bool, default is false) indicates that the directory indicated in ModelsDirectory is allowed to be outside the website root (e.g. ~/../../some/place). Due to this being a potential security risk, it is not allowed by default.

• Umbraco.CMS.ModelsBuilder.DebugLevel (int, default is zero) indicates the debug level. Set to greater than zero to enable detailed logging. For internal / development use.

Example Configuration

The example below shows an example configuration using the SourceCodeManual mode.

Models Builder Dashboard

Models Builder ships with a dashboard in the Settings section of Umbraco's backoffice. The dashboard does three things:

• Details on how Models Builder is configured

• Provides a way to generate models (in SourceCodeManual mode only)

• Reports the last error (if any) that would have prevented models from being properly generated

It's possible with Razor to define functions for rendering HTML. We can leverage our strongly typed models when doing this, and even provide overloads for different types of models. That will automatically be called for different models using dynamic

It's not recommended to create a template and doing all the rendering via razor function, but it can be nifty for rendering search results.

A thing that's important to note here is that RenderContent is called from a codeblock, and not as @RenderContent((dynamic) Model); the reason for this is that if you try to use the latter, razor will expect for the function to return something for it to render.

By casting the strongly typed to a dynamic when calling the RenderContent method, you tell C# to do late runtime binding. You also tell it to pick the proper RenderContent implementation depending on the actual Common Language Runtime (CLR) type of the content object. Using dynamic here is OK and will not pollute the rest of the code.

Models are generated as partial classes. In its most basic form, a model for content type TextPage ends up in a TextPage.generated.cs file and looks like:

What is important is the Header property. The rest is (a) a constructor and (b) some static helpers to get the PublishedContentType and the PublishedPropertyType objects:

Composition and Inheritance

Content type composition consists in having content types "inherit" properties from other content types. Contrary to C#, where a class can only inherit from one other class, Umbraco content types can be composed of several other content types.

The TextPage content type could be composed of the MetaInfo content type (and thus inherit properties Author and Keywords) and of the PageInfo content type (and thus inherit properties Title and MainImage).

Each content type that is involved in a composition is generated both as a class and as an interface, and so the MetaInfo content type would be generated as (some code has been removed and altered for simplicity's sake):

And the TextPage model would be generated as (some code has been removed and altered for simplicity's sake):

A content type parent is a tree-related concept: In the Umbraco backoffice, a content type appears underneath its parent, if any. By convention, a content type is always composed of its parent and therefore inherits its properties. However, the parent content type is treated differently, and the child content type directly inherits (as in C# inheritance) from the parent class.

Therefore, assuming that the AboutPage content type is a direct child of TextPage, it would be generated as:

Extending

Because a model is generated as a partial class, it is possible to extend it. That could be by adding a property, by dropping the following code in a TextPage.cs file:

Models builder does not take a custom partial class into account when generating the models. This means that if a custom partial class, inherits from a base class, tries to provide a constructor with the same signature, or implements a generated property, it will cause compilation errors.

Furthermore a generated model will always be instantiated with its default constructor, so if an overloading constructor is created it will never be used.

IModelsGenerator

As of Umbraco 11.4, the IModelsGenerator interface has been added. If you want to customize how the models are generated, you can make your own implementation of the IModelsGenerator interface. You can then overwrite the Umbraco implementation with dependency injection.

The interface can be accessed via Infrastructure.ModelsBuilder.Building.ModelsGenerator.

Best Practices

Extending models should be used to add stateless, local features to models. It should not be used to transform content models into view models or manage trees of content.

Example of good practice

A customer has "posts" that has two "release date" properties. One is a true date picker property and is used to specify an actual date and to order the posts. The other is a string that is used to specify dates such as "Summer 2015" or "Q1 2016". Alongside the title of the post, the customer wants to display the text date, if present, else the actual date. If none of those are present, the Umbraco update date should be used. Keep in mind that each view can contain code to deal with the situation, but it is much more efficient to extend the Post model:

And to simplify the view as:

Example of bad practice

Because, by default, the content object is passed to views, one can be tempted to add view-related properties to the model. Some properties that do not belong to a content model would be:

• A HomePage property that would walk up the tree and return the "home page" content item

• A Menu property that would list the content items to display in a top menu

• Etc.

Generally speaking, anything that is tied to the current request, or that depends on more than the modeled content, is a bad idea. There are much cleaner solutions, such as using true view model classes that would be populated by a true controller and look like:

One can also extend Umbraco's views to provide a special view helper that would give access to important elements of the website, so that views could contain code such as:

Example of ugly practice

The scope and life-cycle of a model is not specified. In other words, you don't know whether the model exists only for you and for the context of the current request, or if it is cached by Umbraco and shared by all requests.

As a consequence, the following code has a major issue: the TextPage model "caches" an instance of the HomePageDocument model that will never be updated if the home page is re-published.

As a rule of thumb, models should never, ever reference and cache other models.

When using compositions, Models Builder generates an interface for the composed model, which enables us to not have to switch back to using Value() for the composed properties.

A common use-case for this is if you have a separate composition for the "SEO properties" Page Title and Page Description.

You would usually use this composition on both your Home and Textpage document types. Since both Home and Textpage will implement the generated ISeoProperties interface, you will still be able to use the simpler models builder syntax (e.g. Model.PageTitle).

However, you won't be able to use the nice models builder syntax on any master template, since a master template needs to be bound to a generic IPublishedContent. So you'd have to resort to the ever-so-slightly clumsier Model.Value("pageTitle") syntax to render these properties. It is possible to solve this issue of master templating, by using partial views, to render the SEO specific properties.

Render with a partial

If you create a partial and change the first line to use the interface name for the model binding, you can use the nice Models Builder syntax when rendering the properties, like this:

You can then render the partial from your Master Template with something like this (assuming the partial is named Metatags.cshtml):

It's important to note though, that this master template will only work for content types that use the Seo Properties composition.

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.

View components 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:

  Copy

  [ViewComponent(Name = "Employee")]
  public class EmployeeViewComponent : ViewComponent
  {}

• Returns a Task object as IViewComponentResult:

  Copy

  public IViewComponentResult Invoke()
  {
      return Content("Hi I'm an Employee Component");
  }

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:

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;

namespace Umbraco.Docs.Samples.Web.Components.ProductView;

public class ProductViewViewComponent : ViewComponent
{
    public IViewComponentResult Invoke()
    {
        List<string> products = new List<string>() {
            "Product 1", "Product 2", "Product 3", "Product 4", "Product 5"
        };

        return View(products);
    }
}

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:

<h1> Welcome to your Home Page </h1>
<h2>Products List</h2>
<ul>
    @foreach (var product in Model)
    {
        <li>@product</li>
    }
</ul>

UmbracoHelper in a ViewComponent

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

@inject Umbraco.Cms.Web.Common.UmbracoHelper Umbraco

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:

 @(await Component.InvokeAsync("ProductView"))

You can read about different ways of invoking your view component in the View components in ASP.NET Core section of the Microsoft Documentation.view=aspnetcore-5.0)

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}

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

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.

ViewComponents

Using MVC Child Actions in Umbraco

Querying

How to query for published data in your Views

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):

// to return IPublishedContent
@Umbraco.Content(1234)

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

// to return the strongly typed (IEnumerable<Umbraco.Core.Models.IPublishedContent>) collection
@Umbraco.Content(1234, 4321, 1111, 2222)

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.

// to return the Umbraco.Core.Models.IPublishedContent
@Umbraco.Content(Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1"))

You can also pass a Udi to retrieve the content.

// to return the Umbraco.Core.Models.IPublishedContent
@Umbraco.Content(Udi.Create("document", Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1")))

The same query structures apply to media:

@Umbraco.Media(9999)
@Umbraco.Media(9999,8888,7777)
@Umbraco.Media(9999)
@Umbraco.Media(9999,8888,7777)
@Umbraco.Content(Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1"))
@Umbraco.Content(Udi.Create("media", Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1")))

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>

Children() // this is the same as using the Children property on the content item.
Ancestors()
Ancestors(int level)
Ancestors(string nodeTypeAlias)
AncestorsOrSelf()
AncestorsOrSelf(int level)
AncestorsOrSelf(string nodeTypeAlias)
Descendants()
Descendants(int level)
Descendants(string nodeTypeAlias)
DescendantsOrSelf()
DescendantsOrSelf(int level)
DescendantsOrSelf(string nodeTypeAlias)
Siblings()
SiblingsAndSelf()

Additionally there are other methods that will return a single IPublishedContent

Ancestor()
AncestorOrSelf()
AncestorOrSelf(int level)
AncestorOrSelf(string nodeTypeAlias)
AncestorOrSelf(Func<IPublishedContent, bool> func)

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

@Model.Children.Where(x => x.IsVisible())

Traverse for sitemap

var items = @Model.Children.Where(x => x.IsVisible() && x.Level <= 4)

Content sub menu

@Model.AncestorOrSelf(1).Children.Where(x => x.DocumentTypeAlias == "DatatypesFolder").First().Children

Complex query

With the strongly typed IPublishedContent you can do complex queries.

// This example gets the top level ancestor for the current node, and then gets
// the first node found that contains "1173" in the array of comma delimited
// values found in a property called 'selectedNodes'.

var result = @Model.Ancestors().OrderBy(x => x.Level)
    .Single()
    .Descendants()
    .FirstOrDefault(x => x.GetPropertyValue("selectedNodes", "").Split(',').Contains("1173"));

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

Rendering the raw value of a field from IPublishedContent

@Model.Value("bodyContent")

Rendering the converted value of a field from IPublishedContent

@Model.Value<double>("amount")
@Model.Value<IHtmlString>("bodyContent")

Rendering a macro

@Umbraco.RenderMacro("myMacroAlias")

Rendering a macro with parameters using an anonymous object

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

Rendering a macro with parameters using a dictionary

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

Rendering some member data

@if(Members.IsLoggedIn()){
    var profile = Members.GetCurrentMemberProfileModel();
    var umbracomember = Members.GetByUsername(profile.UserName);

    <h1>@umbracomember.Name</h1>
    <p>@umbracomember.Value<string>("bio")</p>
}

This section will show you how to use MVC Partial Views in Umbraco.

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 reuse 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.

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.