1 of 48

Built-in Property Editors

Checkbox List

Alias: Umbraco.CheckBoxList

Returns: IEnumerable<string>

Displays a list of preset values as a list of checkbox controls. The text saved is an IEnumerable collection of the text values.

Unlike other property editors, the Prevalue IDs are not directly accessible in Razor.

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

@{
    if (Model.HasValue("superHeros"))
    {
        <ul>
            @foreach (var item in Model.Value<IEnumerable<string>>("superHeros"))
            {
                <li>@item</li>
            }
        </ul>
    }
}

With Modelsbuilder

@{
    if (Model.SuperHeros.Any())
    {
        <ul>
            @foreach (var item in Model.SuperHeros)
            {
                <li>@item</li>
            }
        </ul>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

The example below demonstrates how to add values programmatically using a Razor view. However, this is used for illustrative purposes only and is not the recommended method for production environments.

@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@using Newtonsoft.Json
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'superHeros'.
    content.SetValue("superHeros", JsonConvert.SerializeObject(new[] { "Umbraco", "CodeGarden"}));

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234);
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{

// Set the value of the property with alias 'superHeros'
content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor,x => x.SuperHeros).Alias, JsonConvert.SerializeObject(new[] { "Umbraco", "CodeGarden"}));
}

Color Picker

Alias: Umbraco.ColorPicker

Returns: String (Hexadecimal)

Returns: Umbraco.Cms.Core.PropertyEditors.ValueConverters.ColorPickerValueConverter.PickedColor (When using labels)

The Color picker allows you to set some predetermined colors that the editor can choose between.

It's possible to add a label to use with the color.

Data Type Definition Example

Content Example

Example with Modelsbuilder

@{
    // Model has a property called "Color" which holds a Color Picker editor
    var hexColor = Model.Color;
    // Define the label if you've included it
    String colorLabel = Model.Color.Label;

    if (hexColor != null)
    {
        <div style="background-color: #@hexColor">@colorLabel</div>
    }
}

Example without Modelsbuilder

@using Umbraco.Cms.Core.PropertyEditors.ValueConverters
@{
    // Model has a property called "Color" which holds a Color Picker editor
    var hexColor = Model.Value("Color");
    // Define the label if you've included it
    var colorLabel = Model.Value<ColorPickerValueConverter.PickedColor>("Color").Label;

    if (hexColor != null)
    {
        <div style="background-color: #@hexColor">@colorLabel</div>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'color'. 
    // The value set here, needs to be one of the prevalues on the Color Picker
    content.SetValue("color", "38761d");

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{
    // Set the value of the property with alias 'color'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Color).Alias, "38761d");
}

Content Picker

Alias: Umbraco.ContentPicker

Returns: IPublishedContent

The content picker opens a panel to pick a specific page from the content structure. The value saved is the selected nodes

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

With Modelsbuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

DateTime

Alias: Umbraco.DateTime

Returns: DateTime

Displays a calendar UI for selecting dates which are saved as a DateTime value.

Data Type Definition Example

There are two settings available for manipulating the DateTime property.

One is to set a format. By default the format of the date in the Umbraco backoffice will be YYYY-MM-DD HH:mm:ss, but you can change this to something else. See MomentJS.com for the supported formats.

The second setting is "Offset time". When enabling this setting the displayed time will be offset with the servers timezone. This can be useful in cases where an editor is in a different timezone than the hosted server.

Content Example

MVC View Example - displays a datetime

With Modelsbuilder

@Model.DatePicker

Without Modelsbuilder

@Model.Value("datePicker")

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'datePicker'
    content.SetValue("datePicker", DateTime.Now);

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{

    // Set the value of the property with alias 'datePicker'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.DatePicker).Alias, DateTime.Now);
}

Date

Returns: Date

Displays a calendar UI for selecting dates which are saved as a DateTime value.

Data Type Definition Example

The only setting that is available for manipulating the Date property is to set a format. By default the format of the date in the Umbraco backoffice will be YYYY-MM-DD, but you can change this to something else. See MomentJS.com for the supported formats.

Content Example

MVC View Example - displays a datetime

Typed

@(Model.Content.GetPropertyValue<DateTime>("datePicker").ToString("dd MM yyyy"))

Dynamic (Obsolete)

See Common pitfalls for more information about why the dynamic approach is obsolete.

@{
    @CurrentPage.datePicker.ToString("dd-MM-yyyy")
}

Decimal

Alias: Umbraco.Decimal

Returns: decimal

Data Type Definition Example

In the example above the possible values for the input field would be [8, 8.5, 9, 9.5, 10]

All other values will be removed in the content editor when saving or publishing.

If the value of Step Size is not set then all decimal values between 8 and 10 is possible to input in the content editor.

Content Example

MVC View Example

With Modelsbuilder

@Model.MyDecimal

Without Modelsbuilder

@Model.Value("MyDecimal")

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@inject IContentService Services;
@using Umbraco.Cms.Core.Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'myDecimal'. 
    content.SetValue("myDecimal", 3);

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;
@{
    // Set the value of the property with alias 'myDecimal'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MyDecimal).Alias, 3);
}

Email Address

In this article you can learn how to use the build in email property editor

Alias: Umbraco.EmailAddress

Returns: String

Displays an email address.

Settings

The Email Address Property Editor does not come with any further configuration. The property can be configured once it has been added to a Document Type.

Content Example

MVC View Example

Without Modelsbuilder

@if (Model.HasValue("email"))
{
    var emailAddress = Model.Value<string>("email");
    <p>@emailAddress</p>
}

With Modelsbuilder

@if (!string.IsNullOrWhiteSpace(Model.Email))
{
    <p>@Model.Email</p>
}

Add value programmatically

See the example below to learn how a value can be added or changed programmatically to an Email-address property. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;

@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of your page
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");

    // Get the page using the GUID you've just defined
    var content = contentService.GetById(guid);
    // Set the value of the property with alias 'email'
    content.SetValue("email", "jpk@umbraco.dk");

    // Save the change
    contentService.Save(content);
}

The value sent to an EmailAddress property needs to be a correct email address, For example: name@domain.com.

It is recommended that you set up validation on this property, in order to verify whether the value added is in the correct format.

Eye Dropper Color Picker

Alias: Umbraco.ColorPicker.EyeDropper

Returns: string

The Eye Dropper Color picker allows you to choose a color from the full color spectrum using HEX and RGBA.

Data Type Definition Example

Content Example

Example with Modelsbuilder

Example without Modelsbuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

File Upload

Alias: Umbraco.UploadField

Returns: string

Adds an upload field, which allows documents or images to be uploaded to Umbraco.

You can define which file types should be accepted through the upload field.

For uploading and adding files and images to your Umbraco project, we recommend using the Media Picker.

Find the full documentation for the property in the article.

Data Type Definition Example

Content Example

In code, the property is a string, which references the location of the file.

Example: "/media/o01axaqu/guidelines-on-remote-working.pdf"

MVC View Example

Without Modelsbuilder

With Modelsbuilder

Add values programmatically

The samples in this section have not been verified against the latest version of Umbraco.

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Image Cropper

Returns: MediaWithCrops

Returns a path to an image, along with information about focal point and available crops.

When the Image Cropper is used on a Media Type the crops are shared between all usages of a Media Item. This is called global crops.

If the Image Cropper is used on a Document Type, the file and crops will be local to the Document.

Notice that it is possible make local crops on shared Media Items via the .

Settings

Prevalues

You can add, edit & delete crop presets the cropper UI can use.

Data Type Definition Example

Content Example

The Image Cropper provides a UI to upload an image, set a focal point on the image, and use predefined crops.

By default, images in the Image Cropper will be shown based on a set focal point and only use specific crops if they are available.

The Image Cropper comes with 3 modes:

Uploading an image
Setting a focal point
Cropping the image to predefined crops

Uploading images

The editor exposes a drop area for files. Select it to upload an image.

Set focal point

By default, the Image Cropper allows the editor to set a focal point on the uploaded image.

All the preset crops are shown to give the editor a preview of what the image will look like on the frontend.

Crop and resize

The editor can fit the crop to the image to ensure that the image is presented as intended.

Powered by ImageSharp.Web

Sample code

The Image Cropper comes with an API to generate crop URLs. You can also access the raw data directly as a dynamic object.

For rendering a cropped media item, the .GetCropUrl is used:

The third parameter is HtmlEncode and is by default set to true. This means you only need to define the parameter if you want to disable HTML encoding.

Example to output a "banner" crop from a cropper property with the property alias "customCropper"

Or, alternatively using the MediaWithCrops extension method:

Example to dynamically create a crop using the focal point - in this case 300 x 400px image

CSS background example to output a "banner" crop

Set the htmlEncode to false so that the URL is not HTML encoded

Add values programmatically

The following sample demonstrates how to add or change the value of an Image Cropper property programmatically. The sample creates an API controller with an action, which must be invoked via a POST request to the URL written above the action.

If you use Models Builder to generate source code (modes SourceCodeAuto or SourceCodeManual), you can use nameof([generated property name]) to access the desired property without using a magic string:

Get all the crop urls for a specific image

Crop URLs are not limited to usage within a view. IPublishedContent has a GetCropUrl extension method, which can be used to access crop URLs anywhere.

The following sample demonstrates how to use GetCropUrl to retrieve URLs for all crops defined on a specific image:

Sample on how to change the format of the image

Label

Alias: Umbraco.Label

Returns: String

Label is a non-editable control and can only be used to display a pre-set value.

Data Type Definition Example

Value type

If you want to set a value other than a String, you can define the data using one of the other available Data Types. These include Decimal, Date/time, Time, Integer, and Big integer.

There is also a Value Type: Long string if you need to set a long string value for your Label.

Content Example

MVC View Example

Without ModelsBuilder

With ModelsBuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

List View

Alias: Umbraco.Listview

Returns: IEnumerable<IPublishedContent>

List View display a list of categories when it is enabled on a Document Type that has children.

Enable list view

If enabled, editors will be able to see multiple children from a list on a content node that has children. When not enabled, no list will be shown and all children will be shown in the Content Tree.

Settings

Page Size

Defines how many child content nodes you want to see per page. This will limit how many content items you will see in your list. If you set it to 5, then only 5 content items will be shown in the list.

Order By

Will sort your list by the selection you choose in the dropdown. By default it selects "Last edited" and you get the following three columns:

Last edited - When the content node was last edited and saved.
Name - Name of the content node(s).
Created by - This is the user who the content node was created by.

You can add more sorting to this list by adding more datatypes to the columns in the "Columns Displayed" section.

Order Direction

You can select order of the content nodes displayed, "Acsending" or "Descending". The order is affected by the "Order By" selection.

Columns Displayed

It is possible to add more columns to the list, via adding the properties through the dropdown. These properties are based on the Data Types which are used by the Document Type. It will show up in the dropdown by its alias and not the name on the property.

Once you have selected a column that you want to display, the next thing you want to do is define what its name should be and what kind of value it should display. You can also move the headers around, re-ordering how the headers should look. This is done by the move icon on the left side of the alias.

The template section is where you define what kind of value you want to display. The value of the column is in the value variable.

Layouts

The list view comes with two layouts by default. A list and a grid view. These views can be disabled if you are not interested in any of them.

A minimum of one layout needs to be enabled for the list view to work.

You can also make your own layout and add it to the settings. For example, if you wanted to change the width or length of the grid, you will be able to do so.

Bulk Action Permissions

Select what kind of action is available on the list view.

Allow bulk publish - content only
Allow bulk unpublish - content only
Allow bulk copy - content only
Allow bulk move
Allow bulk delete

Content app icon

Changes the icon in the backoffice of the listview. By default it will look like the image below.

Content app name

You can change the name of the listview itself. Default if empty: 'Child Items'.

Show Content App First

Enable this to show the content app by default instead of the list view

Content Example

Generic field value

The {{ value }} will take the value of the Email property and display it in the list, as shown on the image below.

Member name

First, a Member Picker property needs to be present on the content item. In this example, the child item has gotten a Member Picker Data Type with the alias of isAuthor.

Now that the child item has a member and the value that should be displayed is the name of the picked value, the next step is to reconfigure the template value in the listview setting.

Other examples

Markdown Editor

Alias: Umbraco.MarkdownEditor

Returns: System.Web.HtmlString

This built-in editor allow the user to use the markdown formatting options, from within a tinyMCE-like interface.

Data Type Definition Example

There are three settings available for manipulating the Markdown editor property.

Preview toggles if a preview of the markdown should be displayed beneath the editor in the content view.
Default value is inserted if no content has been saved to the Document Type using this property editor.
Overlay Size is used to select the width of the link picker overlay in the content view.

Content Example

Explanation of buttons from left to right

Other functionality

MVC View Example

With Modelsbuilder

Without Modelsbuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Media Picker

Alias: Umbraco.MediaPicker3

Returns: IEnumerable<MediaWithCrops> or MediaWithCrops

This property editors returns a single MediaWithCrops item if the "Pick multiple items" Data Type setting is disabled or a collection if it is enabled.

Data Type Definition Example

Accepted types

Use setting to limit the picker to only select Media Items of these types.

Pick multiple items

Use this setting to enable the property to contain multiple items. When this is enabled the property editor returns an IEnumerable<MediaWithCrops>.

You can still set the maximum amount to 1. Do so when you want to retrieve a collection but only allow the Content Editors to select one Media Item.

Amount

Use this setting to enforce a minimum and/or maximum amount of selected Media Items.

It is not possible to set a maximum amount when the "Pick multiple items" feature is disabled.

Start node

This setting is used to limit the Media Picker to certain parts of the Media Tree.

Ignorer user start nodes

Use this setting to overrule user permissions, to enable any user of this property to pick any Media Item of the chosen Start node.

When this setting is enabled, a user who doesn't normally have access to the media selected as "Start Node" (/Design in this case), can access the media when using this particular Media Picker. If no Start node has been defined for this property any content can be viewed and selected of this property.

Enable Focal Point

Enable the focal point setter, do only enable this if the focal point is used or if you have Image crops defined.

Image Crops

Define local image crops. Local image crop data is stored on the document in this property. This means it can differentiate between documents.

This is different from Global crops as they are defined on the Media Item, making the crops shared between all usage of that Media Item.

Global crops are configured on the Image Cropper property of the Image Media Type

Read about the Image Cropper here

Content Example

MVC View Example

Multiple enabled without Modelsbuilder

@using Umbraco.Cms.Core.Models
@{
    var typedMultiMediaPicker = Model.Value<IEnumerable<MediaWithCrops>>("medias");
    foreach (var entry in typedMultiMediaPicker)
    {
        <img src="@entry.MediaUrl()" style="width:200px" />
    }
}

Multiple enabled with Modelsbuilder

@{
    var typedMultiMediaPicker = Model.Medias;
    foreach (var entry in typedMultiMediaPicker)
    {
        <img src="@entry.MediaUrl()" style="width:200px" />
    }
}

Multiple disabled without Modelsbuilder

@using Umbraco.Cms.Core.Models
@{
    var typedMediaPickerSingle = Model.Value<MediaWithCrops>("media");
    if (typedMediaPickerSingle != null)
    {
        <img src="@typedMediaPickerSingle.MediaUrl()" style="width:200px" alt="@typedMediaPickerSingle.Value("alt")" />
    }
}

Multiple disabled with Modelsbuilder

@using Umbraco.Cms.Core.Models
@{
    var typedMediaPickerSingle = Model.Media;
    if (typedMediaPickerSingle is MediaWithCrops mediaEntry)
    {
        <img src="@mediaEntry.MediaUrl()" style="width:200px"/>
    }
}

Using crops

Both local and global crops are retrieved using the method GetCropUrl. If crops with identical aliases are defined both locally and globally, the locally defined crops are always prioritized by GetCropUrl.

The following is an example of how to retrieve a crop from a MediaWithCrops entry:

@{
    foreach (var entry in Model.Medias)
    {
        <img src="@entry.GetCropUrl("cropAlias")"/>
    }
}

Explicitly retrieving global crops

You can retrieve globally defined crops explicitly by using GetCropUrl on the UrlHelper:

@{
    foreach (var entry in Model.Medias)
    {
        <img src="@Url.GetCropUrl(entry, "cropAlias")"/>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

The following sample will update a single image in a Media Picker.

@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Get the media you want to assign to the media picker 
    var media = Umbraco.Media("bca8d5fa-de0a-4f2b-9520-02118d8329a8");

    // Create an Udi of the media
    var udi = Udi.Create(Constants.UdiEntityType.Media, media.Key);

    // Set the value of the property with alias 'featuredBanner'. 
    content.SetValue("featuredBanner", udi.ToString());

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    // Set the value of the property with alias 'featuredBanner'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FeaturedBanner).Alias, udi.ToString());
}

Media Picker (Legacy)

We highly recommend that you use the Media Picker instead.

This updated property contains more customizable features, and we recommend using this over the Media Picker, which is also marked as the old version of the picker.

Alias: Umbraco.MediaPicker

Returns: IEnumerable<IPublishedContent> or IPublishedContent

This property editors returns a single item if the "Pick multiple items" Data Type setting is disabled or a collection if it is enabled.

Data Type Definition Example

Ignore user start nodes

Use Settings to overrule user permissions, to enable any user of this property to pick any Media Item of the choosen Start node.

Content Example

MVC View Example

Multiple enabled without Modelsbuilder

@{
    var typedMultiMediaPicker = Model.Value<IEnumerable<IPublishedContent>>("sliders");
    foreach (var item in typedMultiMediaPicker)
    {
        <img src="@item.Url()" style="width:200px"/>
    }
}

Multiple enabled with Modelsbuilder

@{
    var typedMultiMediaPicker = Model.Sliders;
    foreach (var item in typedMultiMediaPicker)
    {
        <img src="@item.Url()" style="width:200px" />
    }
}

Multiple disabled without Modelsbuilder

@{
    var typedMediaPickerSingle = Model.Value<IPublishedContent>("featuredBanner");
    if (typedMediaPickerSingle != null)
    {
        <p>@typedMediaPickerSingle.Url()</p>
        <img src="@typedMediaPickerSingle.Url()" style="width:200px" alt="@typedMediaPickerSingle.Value("alt")" />
    }
}

Multiple disabled with Modelsbuilder

@{
    var typedMediaPickerSingle = Model.FeaturedBanner;
    if (typedMediaPickerSingle is Image image)
    {
        <p>@image.Url()</p>
        <img src="@image.Url()" style="width:200px"/>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Get the media you want to assign to the media picker 
    var media = Umbraco.Media("bca8d5fa-de0a-4f2b-9520-02118d8329a8");

    // Create an Udi of the media
    var udi = Udi.Create(Constants.UdiEntityType.Media, media.Key);

    // Set the value of the property with alias 'featuredBanner'. 
    content.SetValue("featuredBanner", udi.ToString());

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    // Set the value of the property with alias 'featuredBanner'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FeaturedBanner).Alias, udi.ToString());
}

Member Group Picker

Alias: Umbraco.MemberGroupPicker

Returns: string

The Member Group Picker opens a panel to pick one or more member groups from the Member section. The value saved is of type string (comma separated IDs).

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

@if (Model.HasValue("memberGroup"))
{
    var memberGroup = Model.Value<string>("memberGroup"); 
    <p>@memberGroup</p>
}

With Modelsbuilder

@if (!string.IsNullOrEmpty(Model.MemberGroup))
{
    <p>@Model.MemberGroup</p>
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;

@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");
    
    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'memberGroup'. The value is the specific ID of the member group
    content.SetValue("memberGroup", 1067);
            
    // Save the change
    contentService.Save(content);
}

You can also add multiple groups by creating a comma separated string with the desired member group IDs.

@{
    // Set the value of the property with alias 'memberGroup'. 
    content.SetValue("memberGroup", "1067","1068");
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@using Umbraco.Cms.Core;

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    // Set the value of the property with alias 'memberGroup'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MemberGroup).Alias, 1067);
}

Member Picker

Alias: Umbraco.MemberPicker

Returns: IPublishedContent

The member picker opens a panel to pick a specific member from the member section. The value saved is of type IPublishedContent.

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

@{
    if (Model.HasValue("author"))
    {
        var member = Model.Value<IPublishedContent>("author");
        @member.Name
    }
}

With Modelsbuilder

@{
    if (Model.Author != null)
    {
        var member = Model.Author;
        @member.Name
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;

@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Create a variable for the GUID of the member ID
    var authorId = Guid.Parse("ed944097281e4492bcdf783355219450");

    // Set the value of the property with alias 'author'. 
    content.SetValue("author", authorId);

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@using Umbraco.Cms.Core;

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    var udi = Udi.Create(Constants.UdiEntityType.Member, authorId);
    
    // Set the value of the property with alias 'author'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Author).Alias, udi);
}

Multi Url Picker

Alias: Umbraco.MultiUrlPicker

Returns: IEnumerable<Link> or Link

Multi Url Picker allows an editor to pick and sort multiple urls. This property editor returns a single item if the "Maximum number of items" Data Type setting is set to 1 or a collection if it is 0. These can either be internal, external or media.

Data Type Definition Example

Content Example

MVC View Example - value converters enabled

Typed

@using Umbraco.Cms.Core.Models
@{
    var links = Model.Value<IEnumerable<Link>>("footerLinks");
    if (links.Any())
    {
        <ul>
            @foreach (var link in links)
            {
                <li><a href="@link.Url" target="@link.Target">@link.Name</a></li>
            }
        </ul>
    }
}

If Max number of items is configured to 1

@using Umbraco.Cms.Core.Models
@{
    var link = Model.Value<Link>("link");
    if (link != null)
    {
        <a href="@link.Url" target="@link.Target">@link.Name</a>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Services;
@using Newtonsoft.Json;
@using Umbraco.Cms.Core.Models;
@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Get the media you want to assign to the footer links property 
    var media = Umbraco.Media("bca8d5fa-de0a-4f2b-9520-02118d8329a8");

    // Create an Udi of the media
    var mediaUdi = Udi.Create(Constants.UdiEntityType.Media, media.Key);

    // Get the content you want to assign to the footer links property 
    var contentPage = Umbraco.Content("665d7368-e43e-4a83-b1d4-43853860dc45");

    // Create an Udi of the Content
    var contentPageUdi = Udi.Create(Constants.UdiEntityType.Document, contentPage.Key);

    // Create a list with different link types
    var externalLink = new List<Link>
    {
        // External Link
        new Link
        {
            Target = "_blank",
            Name = "Our Umbraco",
            Url = "https://our.umbraco.com/",
            Type = LinkType.External
        },
        // Media 
        new Link
        {
            Target = "_self",
            Name = media.Name,
            Url = media.MediaUrl(),
            Type = LinkType.Media,
            Udi = mediaUdi
        }, 
        // Content 
        new Link
        {
            Target = "_self",
            Name = contentPage.Name,
            Url = contentPage.Url(),
            Type = LinkType.Content,
            Udi = contentPageUdi
        }
    };

    // Serialize the list with links to JSON
    var links = JsonConvert.SerializeObject(externalLink);


    // Set the value of the property with alias 'footerLinks'. 
    content.SetValue("footerLinks", links);

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    // Set the value of the property with alias 'footerLinks'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.FooterLinks).Alias, links);
}

Multinode Treepicker

Alias: Umbraco.MultiNodeTreePicker

Returns: IEnumerable<IPublishedContent>

Settings

The Multinode Treepicker allows you to configure the type of tree to render and what part of the tree that should be rendered. For content it allows you to select a dynamic root node based on the current document using the multinode tree picker.

Node type: set the type of node, the root node of the tree, or query for the root node

For querying for a root node, you can use dynamic placeholders in the XPath query, following the below sample queries

// get the first textpage below the current document
$current/textpage: current page or closest found ancestor

// get a descendant of type news article somewhere below the parent
$parent//newsArticle: parent page or closest found ancestor

// go to the root of the content tree
$root

// go the ancestor at @level=1 where your website root usually is.
$site: Ancestor node at level 1

It is important to notice that all placeholders above act against published content only. So if you, therefore, try to fetch $parent of the current document, then Umbraco will return that or its closest published ancestor. So in case, the parent is not published, it will try the parent of that parent, and so on.

Filter out items with type: allow or disallow tree nodes with a certain content type alias.

Enter typeAlias,altTypeAlias to only allow selecting nodes with those alias'. Enter !typeAlias,altTypeAlias to only allow selecting nodes not with those alias'.

Minimum/maximum number of items: set a limit on the number of items allowed to be selected.

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

@{
    var typedMultiNodeTreePicker = Model.Value<IEnumerable<IPublishedContent>>("featuredArticles");
    if (typedMultiNodeTreePicker != null) {
        foreach (var item in typedMultiNodeTreePicker)
        {
            <p>@item.Name</p>
        }
}

With Modelsbuilder

@{
    var typedMultiNodeTreePicker = Model.FeaturedArticles;
    foreach (var item in typedMultiNodeTreePicker)
    {
        <p>@item.Name</p>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@inject IContentService Services;
@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Services 

@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = Guid.Parse("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Get the pages you want to assign to the Multinode Treepicker
    var page = Umbraco.Content("665d7368-e43e-4a83-b1d4-43853860dc45");
    var anotherPage = Umbraco.Content("1f8cabd5-2b06-4ca1-9ed5-fbf14d300d59");

    // Create Udi's of the pages
    var pageUdi = Udi.Create(Constants.UdiEntityType.Document, page.Key);
    var anotherPageUdi = Udi.Create(Constants.UdiEntityType.Document, anotherPage.Key);

    // Create a list of the page udi's
    var udis = new List<string>{pageUdi.ToString(), anotherPageUdi.ToString()};

    // Set the value of the property with alias 'featuredArticles'. 
    content.SetValue("featuredArticles", string.Join(",", udis));

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@using Umbraco.Cms.Core.PublishedCache;

@{
    // Set the value of the property with alias 'featuredArticles'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor ,x => x.FeaturedArticles).Alias, string.Join(",", udis));
}

Repeatable Textstrings

Alias: Umbraco.MultipleTextstring

Returns: array of strings

The Repeatable textstrings property editor enables a content editor to make a list of text items. For best use with an unordered-list.

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

With Modelsbuilder

Add values programmatically

To add multiple values to the repeatable text strings property editor you have to put each value on a new line. This can be achieved using either \r\n\ or Environment.NewLine.

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Nested Content (Legacy)

We highly recommend that you use the instead.

Nested Content has been marked as obsolete and development on the property editor has been discontinued.

Alias: Umbraco.NestedContent

Returns: IEnumerable<IPublishedElement> (or IPublishedElement depending on configuration)

Nested Content is a list editing property editor, using Element Types to define the list item schema. By using Document Types you have the benefit of a reusable UI that you are familiar with and get to re-use all the standard Data Types as field editors. This property editor returns either a single item or a collection of this Document Type.

The Element Types that Nested Content uses are specialized Document Types - they can be found in the same section as Document Types. However, it is not possible to create content directly in the content tree with an Element Type - it is meant to be used in complex editors like Nested Content or Blocklist.

Configuring Nested Content

The Nested Content property editor is set-up/configured in the same way as any standard property editor, via the Data Types admin interface. To set-up your Nested Content property, create a new Data Type and select Nested Content from the list of available property editors.

You should then be presented with the Nested Content property editors Data Type editor as shown below.

The Data Type editor allows you to configure the following properties:

Doc Types - Defines a list of Document Types to use as data blueprints for this Nested Content instance. For each Document Type, you can provide the alias of the group you wish to render (the first group is used by default if not set) as well as a template for generating list item labels using the syntax {{propertyAlias}}.
- If you would like to include the Document Type name in the label, you can use {{alias}}.
- If you would like to include the index position in the label, you can use {{$index}}.
- If your property links to a content, media or member node, you can use the Angular filter {{ pickerAlias | ncNodeName }} to show the node name rather than the node ID.
- If your property is a rich text editor, you can use the Angular filter {{ pickerAlias | ncRichText }} to show the unformatted text.
- You can use conditional logic to show text instead of 1 or 0 for a true/false property: {{checkboxPickerAlias == 1 ? 'Yes' : 'No'}}.
- For more complex property types, you can display specific attributes by referencing the JSON attribute. For example, if using the MultiUrlPicker, show the name of the first link using {{urlPickerAlias[0]["name"]}}.
Min Items - Sets the minimum number of items that should be allowed in the list. If greater than 0, Nested Content will pre-populate your list with the minimum amount of allowed items and prevent deleting items below this level. Defaults to 0.
Max Items - Sets the maximum number of items that should be allowed in the list. If greater than 0, Nested Content will prevent new items being added to the list above this threshold. Defaults to 0.
Confirm Deletes - Enabling this will demand item deletions to require a confirmation before being deleted. Defaults to true.
Show Icons - Enabling this will display the item's Document Type icon next to the name in the Nested Content list.
Hide Label - Enabling this will hide the property editor's label and expand the Nested Content property editor to the full width of the editor window.

Once your Data Type has been configured, set-up a property on your page Document Type using your new Data Type and you are set to start editing.

Limitations

There is a handful of editors that Nested Content does not support in its elements. These include:

Editing Nested Content

When viewing a Nested Content editor for the first time, you'll be presented with an icon and help text to get you started.

Click the plus icon to start creating a new item in the list.

If your Nested Content editor is configured with multiple document-types you will be presented with a dialog window to select which Document Type you would like to use.

Click the icon of the Document Type you wish to use and a new item will be created in the list using that Document Type.

If you only have one Document Type configured for your Nested Content editor, then clicking the plus icon will not display the dialog and instead will jump straight to inserting an entry in the editor for you ready to edit.

More items can be added to the list by clicking the plus icon for each additional item.

To close the editor for an item or open the editor for another item in the list, you click the edit icon.

To reorder the list, click and drag the move icon up and down to place the items in the order you want.

To delete an item click the delete icon. If the minimum number of items is reached, then the delete icon will appear greyed out to prevent going below the minimum allowed number of items.

Single Item Mode

If Nested Content is configured with a minimum and maximum item of 1, then it goes into single item mode.

In single item mode, there is no icon displayed to add new items, and the single items editor will be open by default and its header bar removed.

In this mode, Nested Content works more like a fieldset than a list editor.

Rendering Nested Content

To render the stored value of your Nested Content property, a built in value converter is provided for you. Call the Value<T> method with a generic type of IEnumerable<IPublishedElement> and the stored value will be returned as a list of IPublishedElement entities.

Example:

Each item is treated as a standard IPublishedElement entity, which means you can use all the value converters you are used to using.

Example:

Single Item Mode

If your Nested Content property editor is configured in single item mode, then the value converter will automatically know this and return a single IPublishedElement entity rather than an IEnumerable<IPublishedElement> list. Therefore, when using Nested Content in single item mode, you can call Value<T> with a generic type of IPublishedElement and you can start accessing the entity's properties straight away, rather than having to then fetch it from a list first.

Example:

Creating Nested Content programmatically

For the sake of this example, let us assume we have a Nested Content property with alias attendeeList, where the element Document Type has an alias of attendee. It has the Properties: user_name, user_email, join_time, leave_time, duration, phone.

To save data in Nested Content, we need to create a new C# List containing a Dictionary of type <string, object>. Dictionary<string, string> would also work. The first dictionary item property/parameter we should specify for each Nested Content element is ncContentTypeAlias, which is the alias of the Document Type that we have nested.

Afterwards, the entire list needs to be serialized to Json via JsonConvert.

In the above sample we iterate through a list of participants (the data for such participants could be coming from an API, for example), and add a new Dictionary item for each person in the list.

Numeric

Alias: Umbraco.Integer

Returns: Integer

Numeric is an HTML input control for entering numbers. Since it's a standard HTML element the options and behaviour are all controlled by the browser and therefore is beyond the control of Umbraco.

Data Type Definition Example

Minimum

This allows you to set up a minimum value. If you will always need a minimum value of 10 this is where you set it up and whenever you use the datatype the value will always start at 10. It's not possible to change the value to anything lower than 10. Only higher values will be accepted.

Step Size

This allows you to control by how much value should be allowed to increase/decrease when clicking the up/down arrows. If you try to enter a value that does not match with the step setting then it will not be accepted.

Maximum

This allows you to set up a maximum value. If you will always need a maximum value of 100 this is where you set it up. It's not possible to change the value to anything higher than 100. Only lower values will be accepted.

Settings

Content Example

MVC View Examples

Rendering the output casting to an int (without Modelsbuilder)

By casting the output as an int it's possible for you to do mathematical operations with the value.

Rendering the output casting to a string (Without Modelsbuilder)

You can also render the output by casting it to a string, which means you will not be able to do mathematical operations

With Modelsbuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Radiobutton List

Alias: Umbraco.RadioButtonList

Returns: string

Pretty much like the name indicates this Data type enables editors to choose from list of radio buttons and returns the value of the selected item as string.

Data Type Definition Example

Content Example

MVC View Example

Typed

Without Modelsbuilder

With Modelsbuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Slider

Alias: Umbraco.Slider

Returns: decimal or Umbraco.Core.Models.Range<decimal>

Pretty much like the name indicates this Data type enables editors to choose a value with a range using a slider.

There are two flavors of the slider. One with a single value picker. One with a minimum and maximum value.

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

With Modelsbuilder

Add values programmatically

With a range off

With a range on

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Textarea

Alias: Umbraco.TextArea

Returns: String

Textarea is an HTML textarea control for multiple lines of text. It can be configured to have a fixed character limit, as well as define how big the space for writing can be. By default, there is no character limit unless it's specifically set to a specific value like 200 for instance. If you don't specify the number of rows, 10 will be the amount of rows the textarea will be occupying, unless changed to a custom value.

Data Type Definition Example

Without a character limit

With a character limit

Settings

Content Example

Without a character and rows limit

With a character limit and rows limit

MVC View Example

Without Modelsbuilder

@{
    if (Model.HasValue("description")){
        <p>@(Model.Value<string>("description"))</p>
    }
}

With Modelsbuilder

@if (!Model.HasValue(Model.Description))
{
   <p>@Model.Description</p>
}

Add value programmatically

See the example below to learn how a value can be added or changed programmatically to a Textarea property. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;
@inject IContentService Services;

@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of your page
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");

    // Get the page using the GUID you've just defined
    var content = contentService.GetById(guid);
    // Set the value of the property with alias 'description'
    content.SetValue("description", "This is some text for the text area!");

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{

    // Set the value of the property with alias 'description'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Description).Alias, "This is some text for the text area!");
}

Textbox

Alias: Umbraco.Textbox

Returns: String

Textbox is an HTML input control for text. It can be configured to have a fixed character limit. The default maximum amount of characters is 512 unless it's specifically changed to a lower amount.

Data Type Definition Example

Content Example

Without a character limit

With a character limit

MVC View Example

Without Modelsbuilder

@{
    // Perform an null-check on the field with alias 'pageTitle'
    if (Model.HasValue("pageTitle")){
        // Print the value of the field with alias 'pageTitle'
        <p>@(Model.Value("pageTitle"))</p>
    }
}

With Modelsbuilder

@{
    // Perform an null-check on the field with alias 'pageTitle'
    @if (!Model.HasValue(Model.PageTitle))
    {
        // Print the value of the field with alias 'pageTitle'
        <p>@Model.PageTitle</p>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("32e60db4-1283-4caa-9645-f2153f9888ef");

    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'pageTitle'
    content.SetValue("pageTitle", "Umbraco Demo");

    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{

    // Set the value of the property with alias 'pageTitle'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.PageTitle).Alias, "Umbraco Demo");
}

Toggle

Returns: Boolean

Toggle is a standard checkbox which saves either 0 or 1, depending on the checkbox being checked or not.

Data Type Definition Example

The Toggle property has a setting which allows you to set the default value of the checkbox, either checked (true) or unchecked (false).

It is also possible to define a label, that will be displayed next to the checkbox on the content.

Content Example

MVC View Example

Without Modelsbuilder

@{
    if (!Model.Value<bool>("myCheckBox"))
    {
        <p>The Checkbox is not checked!</p>
    }
}

With Modelsbuilder

@{
    if (!Model.MyCheckbox)
    {
        <p>The Checkbox is not checked!</p>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@using Umbraco.Cms.Core.Services;
@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");
    
    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'myCheckBox'
    content.SetValue("myCheckBox", true);
            
    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@using Umbraco.Cms.Core.PublishedCache;
@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    // Set the value of the property with alias 'myCheckBox'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor,x => x.MyCheckBox).Alias, true);

}

User Picker

Alias: Umbraco.UserPicker

Returns: IPublishedContent

The user picker opens a panel to pick a specific user from the Users section. The value saved is of type IPublishedContent.

Data Type Definition Example

Content Example

MVC View Example

Getting the Value of the property will return the user ID - properties of the User can be accessed by referencing UserService.

Without Modelsbuilder

@using Umbraco.Cms.Core.Services;
@inject IUserService UserService;
@{
    
    if (Model.Value("userPicker") != null)
    {
        var us = UserService;
        var username = us.GetUserById(Model.Value<int>("userPicker")).Name;

        <p>This is the chosen person: @username</p>
        <p>This returns the id value of chosen person: @Model.Value("userPicker")</p>
    }
}

With Modelsbuilder

@using Umbraco.Cms.Core.Services;
@inject IUserService UserService;
@{
    if (Model.UserPicker != null)
    {

        var us = UserService;
        var user = us.GetUserById((int)Model.UserPicker);

        <p>This is the chosen person: @user.Name</p>
        <p>This returns the id value of chosen person: @user.Id)</p>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update a value of a property editor you need the Content Service.

@inject IContentService Services;
@{
    // Get access to ContentService
    var contentService = Services;

    // Create a variable for the GUID of the page you want to update
    var guid = new Guid("796a8d5c-b7bb-46d9-bc57-ab834d0d1248");
    
    // Get the page using the GUID you've defined
    var content = contentService.GetById(guid); // ID of your page

    // Set the value of the property with alias 'userPicker'. The value is the specific ID of the user
    content.SetValue("userPicker", -1);
            
    // Save the change
    contentService.Save(content);
}

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

@{
    // Get the page using it's id
    var content = contentService.GetById(1234); 
}

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

@inject IPublishedSnapshotAccessor _publishedSnapshotAccessor;
@{
    // Set the value of the property with alias 'userPicker'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.UserPicker).Alias, "Umbraco Demo");
}

Block Editors

The Block Editors are property editors that enables you to build advanced editor tools using a set of predefined Document Types.

Umbraco 10 initially shipped with one Block Editor which is Block List. Block Grid editor has been introduced from version 10.4.0.

Block List

Block Grid

Block List

Alias: Umbraco.BlockList

Returns: IEnumerable<BlockListItem>

Block List is a list editing property editor, using to define the list item schema.

A default Umbraco CMS installation does not ship with a defined Data Type using the Block List editor. In order to start using the property, follow the steps outlined below.

Configure Block List

The Block List property editor is configured in the same way as any standard property editor, via the Data Types admin interface.

To set up your Block List Editor property, create a new Data Type and select Block List from the list of available property editors.

Then you will see the configuration options for a Block List as shown below.

The Data Type editor allows you to configure the following properties:

Available Blocks - Here you will define the Block Types to be available for use in the property. Read more on how to set up Block Types below.
Amount - Sets the minimum and/or maximum number of blocks that should be allowed in the list.
Single block mode - When in Single block mode, the output will be BlockListItem<> instead of BlockListModel-
Live editing mode - Enabling this will make editing of a block happen directly to the document model, making changes appear as you type.
Inline editing mode - Enabling this will change editing experience to inline, meaning that editing the data of blocks happens at sight as accordions.
Property editor width - Overwrite the width of the property editor. This field takes any valid css value for "max-width".

Setup Block Types

Block Types are Element Types which need to be created before you can start configuring them as Block Types. This can be done either directly from the property editor setup process, or you can set them up beforehand and add them to the block list after.

Once you have added an element type as a Block Type on your Block List Data Type you will have the option to configure it further.

Each Block has a set of properties that are optional to configure. They are described below.

Editor Appearance

By configuring the properties in the group you can customize the user experience for your content editors when they work with the blocks in the Content section.

Custom view - Overwrite the AngularJS view for the block presentation in the Content editor. Use this to make a more visual presentation of the block or even make your own editing experience by adding your own AngularJS controller to the view.
Custom stylesheet - Pick your own stylesheet to be used for this block in the Content editor. By adding a stylesheet the styling of this block will become scoped. Meaning that backoffice styles are no longer present for the view of this block.
Overlay editor size - Set the size for the Content editor overlay for editing this block.

Data Models

It is possible to use two separate Element Types for your Block Types. Its required to have one for Content and optional to add one for Settings.

Content model - This presents the Element Type used as model for the content section of this Block. This cannot be changed, but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.
Settings model - Add a Settings section to your Block based on a given Element Type. When picked you can open the Element Type or choose to remove the settings section again.

Catalogue appearance

These properties refers to how the Block is presented in the Block catalogue, when editors choose which Blocks to use for their content.

Background color - Define a background color to be displayed beneath the icon or thumbnail. Eg. #424242.
Icon color - Change the color of the Element Type icon. Eg. #242424.
Thumbnail - Pick an image or SVG file to replace the icon of this Block in the catalogue.

The thumbnails for the catalogue are presented in the format of 16:10, and we recommend a resolution of 400px width and 250px height.

Advanced

These properties are relevant when you work with custom views.

Force hide content editor - If you made a custom view that enables you to edit the content part of a block and you are using default editing mode (not inline) you might want to hide the content-editor from the block editor overlay.

Editing Blocks

When viewing a Block List editor in the Content section for the first time, you will be presented with the option to Add content.

Clicking the Add content button brings up the Block Catalogue.

The Block Catalogue looks different depending on the amount of available Blocks and their catalogue appearance.

Click the Block Type you wish to create and a new Block will appear in the list.

Depending on whether your Block List Editor is setup to use default or inline editing mode you will see one of the following things happening:

In default mode you will enter the editing overlay of that Block:

In inline editing mode the new Blocks will expand to show its inline editor:

More Blocks can be added to the list by clicking the Add content button or using the inline Add content button that appears on hover between or above existing Blocks.

To reorder the Blocks, click and drag a Block up or down to place in the desired order.

To delete a Block click the trash-bin icon appearing on hover.

Rendering Block List Content

Rendering the stored value of your Block List property can be done in two ways.

1. Default rendering

You can choose to use the built-in rendering mechanism for rendering blocks via a Partial View for each block.

The default rendering method is named GetBlockListHtml() and comes with a few options to go with it. The typical use could be:

"MyBlocks" above is the alias for the Block List editor.

If using ModelsBuilder the example can be simplified:

Example:

To make this work you will need to create a Partial View for each block, named by the alias of the Element Type that is being used as Content Model.

These partial views must be placed in this folder: Views/Partials/BlockList/Components/. Example: Views/Partials/BlockList/Components/MyElementTypeAliasOfContent.cshtml.

A Partial View will receive the model of Umbraco.Core.Models.Blocks.BlockListItem. This gives you the option to access properties of the Content and Settings section of your Block.

In the following example of a Partial view for a Block Type, please note that the MyElementTypeAliasOfContentand MyElementTypeAliasOfSettings should correspond with the selected Element Type Alias for the given model in your case.

Example:

With ModelsBuilder:

2. Build your own rendering

A built-in value converter is available to use the data as you like. Call the Value<T> method with a generic type of IEnumerable<BlockListItem> and the stored value will be returned as a list of BlockListItem entities.

Example:

Each item is a BlockListItem entity that contains two main properties Content and Settings. Each of these is a IPublishedElement which means you can use all the value converters you are used to using.

Example:

Extract Block List Content data

In some cases, you might want to use the Block List Editor to hold some data and not necessarily render a view since the data should be presented in different areas on a page. An example could be a product page with variants stored in a Block List Editor.

In this case, you can extract the variant's data using the following, which returns IEnumerable<IPublishedElement>.

Example:

If using ModelsBuilder the example can be simplified:

Example:

If you know the Block List Editor only uses a single block, you can cast the collection to a specific type T using .OfType<T>() otherwise the return value will be IEnumerable<IPublishedElement>.

Build a Custom Backoffice View

Build a Custom View for a Block

You can choose to customize your editing experience by implementing a custom view for each Block Type of a Block Editor.

By picking a custom view you overwrite the backoffice UI for the given block with your own. This enables you to define how a block should be presented. It can, however, also include interactive elements and be a full custom solution to how data is manipulated. In the Block List Editor the Inline Editing Mode must be disabled for custom backoffice views to appear.

Write your own HTML view

Currently you can only pick HTML files for a custom view. These views are powered by AngularJS and you can write any AngularJS logic.

Your HTML can be anything. If you use it as a representation of the content you would also want the full view to be clickable. This would then open the default editor for editing of your content.

The following example displays the property with the alias headline together with the description inside a button to edit your block.

If you would like to display properties of settings, you can access these by using block.settingsData.myPropertyAlias.

Make Block List Editor custom view draggable

A custom view of Block List Editor needs to have the 'blockelement__draggable-element' class presented to define which part of the Block that is draggable.

Example:

Adding custom implementation to your View

To achieve this you need to add a custom AngularJS controller to your custom view, using the ng-controller attribute:

Create a folder inside the App_Plugins folder called 'CustomBlockView'.

Create two files within the CustomBlockView file: package.manifest and customBlock.controller.js.

Add the following JSON to the package.manifest file:

Umbraco will parse all package.manifest files and load any resources they reference into the backoffice during startup.

The second file, customBlock.controller.js, will be used to register the 'customBlockController' defined using the ng-controller attribute in your custom view.

To register the controller, add the following lines of code:

Example: Displaying an image from a Media Picker

Your block may enable you to 'pick' an image for use as the background for a particular block. If you try to display this image directly in the view using block.data.image, you will see the unique ID and not the image.

You will need to use the ID in our custom AngularJS controller in order to get the ImageUrl to display in our backoffice Block Editor View.

With the setup of files above, you need to amend the customBlock.controller.js file, by injecting the mediaResource to retrieve the image from the ID:

Update the Custom View to use the imageUrl property to display the image:

If you need to use a specific crop, you can inject the imageUrlGeneratorResource resource, which has a getCropUrl(mediaPath, width, height, imageCropMode, animationProcessMode) method:

Configuring Block Editor Label Properties

When configuring a block, the label property allows you to define a label for the appearance of the Block in the editor. The label can use AngularJS template string syntax to display values of properties. Example: My Block {{myPropertyAlias}} will be shown as: My Block FooBar.

You can also use more advanced expressions using AngularJS filters. Example: {{myPropertyAlias | limitTo:100}} or for a property using Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}.

It is also possible to use properties from the settings model by using {{$settings.propertyAlias}}.

Useful Angular filters

As well as the , Umbraco ships with some additional filters which are useful for setting the Label field of Block editors.

Filter

Description

Property type

Parameters

Custom filters

If the filters do not suit your needs, you can create custom filters by creating a plugin in App_Plugins and adding a filter module. You can see an example below:

If you do not have an /App_Plugins folder, you can create it at the root of your project.

Create a plugin by adding a folder inside App_Plugins called MyFilters
Inside the MyFilters folder add a package.manifest file containing:

Add a myFilter.filter.js file containing:

Special variables

Dropdown

Alias: Umbraco.DropDown.Flexible

Returns: String or IEnumerable<string>

Displays a list of preset values. Either a single value or multiple values (formatted as a collection of strings) can be returned.

Settings

Enable multiple choice

If enabled, editors will be able to select multiple values from the dropdown otherwise only a single value can be selected.

Prevalues

Prevalues are the options which are shown in the dropdown list. You can add, edit, or remove values here.

Data Type Definition Example

Content Example

Single Value

Multiple Values

MVC View Example

Single item - without Modelsbuilder

Multiple items - without Modelsbuilder

Single item - with Modelsbuilder

Multiple items - with Modelsbuilder

Add values programmatically

Although the use of a GUID is preferable, you can also use the numeric ID to get the page:

If Modelsbuilder is enabled you can get the alias of the desired property without using a magic string:

Grid Layout (Legacy)

Returns: JSON

Gives editors a grid layout editor which allows them to insert different types of content in a predefined layout.

The basic concept of Grid Layouts.

How to setup your Grid Layout data type.

Add settings and styles.

Explanation of default Grid editors and how to customise them.

Build your own Grid editor from the ground up.

Render content created with Grid Layouts in your templates.

General guidelines when contemplating Grid Layout implementation.

Example how to add values programmatically.

What Are Grid Layouts?

To understand how the grid layout editor works, we must first understand the structure of the grid layouts.

Grid layouts consists of two main areas that need to be configured, grid layout area and grid rows.

Grid Layout

The layout area is where the overall page layout is defined. Layout areas are divided in to layout sections e.g. a sidebar section and content section. The size of the layout sections is defined in columns. For a full-width content area use max number of columns (12 for Bootstrap 3). Each layout section contains one or more rows.

Grid Rows

Grid rows is where the actual content goes. Each row is divided into cells that contain the property editors. The size of the cells is defined in columns. Unlike the layouts sections it is possible to add more cells than the max number of columns - they will stack as they should in a grid system.

Block Grid

Alias: Umbraco.BlockGrid

Returns: BlockGridModel

The Block Grid property editor enables editors to layout their content in the Umbraco backoffice. The content is made of Blocks that can contain different types of data.

Sample configuration

When testing out the property editor, you can use a set of predefined Blocks. The option will only be possible when there are no other Data Types using the Block Grid property editor.

Create a new Data Type.
Select the Block Grid as the Property editor.
Install the "Sample Configuration".

4 Blocks will be added to the property, ready for testing.

Configuring the Block Grid

The Block Grid property editor is configured via the Data Types backoffice interface.

To set up the Block Grid property editor, follow these steps:

Navigate to the Settings section in the Umbraco backoffice.
Right-click the Data Types folder.
Select Create -> New Data Type.
Select Block Grid from the list of available property editors.

You will see the configuration options for a Block Grid property editor as shown below:

The Data Type editor allows you to configure the following properties:

Blocks - Defines the Block Types available for use in the property. For more information, see Setup Block Types.
Amount - Sets the minimum and/or the maximum number of Blocks that should be allowed at the root of the layout.
Live editing mode - Enabling this option will allow you to see the changes as you are editing them.
Editor width - Overwrites the width of the property editor. This field takes any valid CSS value for "max-width". For example: 100% or 800px.
Grid Columns - Define the number of columns in your grid layout. The default is 12 columns.
Layout Stylesheet - Replaces the built-in Layout Stylesheet. Additionally, you can retrieve the default layout stylesheet to use as a base for your own inspiration or for writing your own stylesheet.
Create Button Label - Overwrites the label on the Create button.

Setup Block Types

Block Types are based on Element Types. These can be created beforehand or while setting up your Block Types.

Once you have added an Element Type as a Block Type on your Block Grid Data Type you have the option to configure it.

Examples and more details about configuring the Label property

Groups

Blocks can also be grouped. This is visible in the Block Catalogue and can also be used to allow a group of Blocks in an Area.

Block Configuration Settings

Each Block has a set of properties that are optional to configure. These are described below.

General

Customize the user experience for your content editors when they work with the Blocks in the Content section.

Label - Defines a label for the appearance of the Block in the editor. The label can use AngularJS template-string-syntax to display values of properties.

Label example: "My Block {{myPropertyAlias}}" will be shown as: "My Block FooBar".

You can also use more advanced expression using AngularJS filters, like {{myPropertyAlias | limitTo:100}} or for a property using Richtext editor {{myPropertyAlias | ncRichText | truncate:true:100}}. It is also possible to use properties from the Settings model by using {{$settings.propertyAlias}}.

Get more tips on how to use AngularJS filters in Umbraco CMS from this community-made Umbraco AngularJS filter cheat sheet.

Content model - Presents the Element Type used as model for the Content section of this Block. This cannot be changed but you can open the Element Type to perform edits or view the properties available. Useful when writing your Label.
Settings model - Adds a Settings section to your Block based on a given Element Type. When selected you can open the Element Type or choose to remove the Settings section again.

Size options

Customize the Blocks size in the Grid. If you define multiple options, the Block becomes scalable.

By default, a Block takes up the available width.

A Block can be resized in two ways:

When a Block is placed in an Area, it will fit to the Areas width. Learn more about Areas.
A Block can have one or more Column Span options defined.

A Column Span option is used to define the width of a Block. With multiple Column Span options defined, the Content Editor can scale the Block to fit specific needs.

Additionally, Blocks can be configured to span rows, this enables one Block to be placed next to a few rows containing other Blocks.

Available column spans - Defines one or more columns, the Block spans across. For example: in a 12 columns grid, 6 columns is equivalent to half width. By enabling 6 columns and 12 columns, the Block can be scaled to either half width or full width.
Available row spans - Defines the amount of rows the Block spans across.

See the scaling blocks section of this article for an example of how scaling works.

Catalogue appearance

These properties refer to how the Block is presented in the Block catalogue when editors choose which Blocks to use for their content.

Background color - Defines a background color to be displayed beneath the icon or thumbnail. Example: #424242.
Icon color - Changes the color of the Element Type icon. Example: #242424.
Thumbnail - Pick an image or Scalable Vector Graphics (SVG) file to replace the icon of the Block in the catalogue.

The thumbnails for the catalogue are presented in the format of 16:10. We recommend a resolution of 400px width and 250px height.

Permissions

Allow in root - Determines whether the Block can be created at the root of your layout. Turn this off if you only want a Block to appear within Block Areas.
Allow in areas - Determines whether the Block can be created inside Areas of other Blocks. If this is turned off it can still be allowed in Block Areas by defining specific allowed Blocks.

Areas

Blocks can nest other Blocks to support specific compositions. These compositions can be used as a layout for other Blocks.

To achieve nesting, a Block must have one or more Areas defined. Each Area can contain one or more Blocks.

Each Area has a size, defined by column and rows spans. The grid for the Areas are based on the same amount of columns as your root grid, unless you choose to change it.

To scale an Area, click and drag the scale-button in the bottom-right corner of an Area.

Grid Columns for Areas - Overwrites the amount of columns used for the Area grid.
Areas - Determines whether the Block can be created inside Areas of other Blocks.

Area configuration

Alias - The alias is used to identify this Area. It is being printed by GetBlockGridHTML() and used as name for the Area slot in Custom Views. The alias is also available for CSS Selectors to target the HTML-Element representing an Area.
Create Button Label - Overwrites the Create Button Label of the Area.
Number of blocks - Determines the total number of Blocks in an Area.
Allowed block types - When this is empty, all Blocks with Permissions for creation in Areas, will be available. This can be overwritten by specifying the allowed Blocks. Define the types of Blocks or Groups of Blocks that are allowed. Additionally, you can also set how many Blocks of each type/group should be present.

When allowing a Group of Blocks, you might want to require a specific amount for a certain Block of that Group. This can be done by adding that Block Type to the list as well and set the requirements.

Advanced

These properties are relevant when working with custom views or complex projects.

Custom view - Overwrites the AngularJS view for the block presentation in the Content editor. Use this view to make a more visual presentation of the Block or make your own editing experience by adding your own AngularJS controller to the view.

Notice that any styling of a Block is scoped. This means that the default backoffice styles are not present for the view of this Block.

Custom stylesheet - Pick your own stylesheet to be used by the Block in the Content editor.
Overlay editor size - Sets the size for the Content editor overlay for editing this block.
Hide content editor - Hides the UI for editing the content in a Block Editor. This is only relevant if you made a custom view that provides the UI for editing of content.

Editing Blocks

When viewing a Block Grid property editor in the Content section for the first time, you will be presented with the option to Add content.

Clicking the Add content button opens up the Block Catalogue.

The Block Catalogue looks different depending on the amount of available Blocks and their catalogue appearance.

Click the Block Type you wish to create and a new Block will appear in the layout.

More Blocks can be added to the layout by clicking the Add content button. Alternatively, use the Add content button that appears on hover to add new Blocks between, besides, or above the existing Blocks.

To delete a Block, click the trash icon which appears on the mouse hover.

Sorting Blocks

Blocks can be rearranged using the click and drag feature. Move them up or down to place them in the desired order.

Moving a Block from one Area to another is done in the same way. If a Block is not allowed in the given position, the area will display a red color and not allow the new position.

Scaling Blocks

If a Block has multiple size options it can be scaled via the UI. This appears in the bottom left corner of the Block.

The Block is resized using a click-and-drag feature. Moving the mouse will change the size to the size options closest to the mouse pointer.

Rendering Block Grid Content

Rendering the stored value of your Block Grid property editor can be done in two ways:

Default rendering
Build your own rendering

1. Default rendering

You can choose to use the built-in rendering mechanism for rendering Blocks using a Partial View for each block.

The default rendering method is named GetBlockGridHtmlAsync() and comes with a few options - for example:

@await Html.GetBlockGridHtmlAsync(Model, "myGrid")

In the sample above "myGrid" is the alias of the Block Grid editor.

If you are using ModelsBuilder, the example will look like this:

@await Html.GetBlockGridHtmlAsync(Model.MyGrid)

To use the GetBlockGridHtmlAsync() method, you will need to create a Partial View for each Block Type. The Partial View must be named using the alias of the Element Type that is being used as Content Model for the Block Type.

These Partial View files need to go into the Views/Partials/blockgrid/Components/ folder.

Example: Views/Partials/blockgrid/Components/MyElementTypeAliasOfContent.cshtml.

The Partial Views will receive a model of type Umbraco.Core.Models.Blocks.BlockGridItem. This model contains Content and Settings from your block, as well as the configured RowSpan, ColumnSpan, ForceLeft, ForceRight, and Areas of the Block.

Rendering the Block Areas

The Partial View for the Block is responsible for rendering its own Block Areas. This is done using another built-in rendering mechanism:

@await Html.GetBlockGridItemAreasHtmlAsync(Model)

Here you will need to create a Partial View for each Block Type within the Block Area. For the name, use the alias of the Element Type that is being used as Content Model for the Block Type.

These Partial Views must be placed in the same folder as before, (Views/Partials/blockgrid/Components/), and will receive a model of type Umbraco.Core.Models.Blocks.BlockGridItem.

Putting it all together

The following is an example of a Partial View for a Block Type of type MyElementTypeAliasOfContent.

MyElementTypeAliasOfContent.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem>;

@* Render the value of field with alias 'heading' from the Element Type selected as Content section *@
<h1>@Model.Content.Value("heading")</h1>

@* Render the block areas *@
@await Html.GetBlockGridItemAreasHtmlAsync(Model)

If you are using ModelsBuilder, you can make the property rendering strongly typed by letting your view accept a model of type BlockGridItem<T>. For example:

MyElementTypeAliasOfContent.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem<ContentModels.MyElementTypeAliasOfContent>>;
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;

@* Render the Heading property from the Element Type selected as Content section *@
<h1>@Model.Content.Heading</h1>

@* Render the block areas *@
@await Html.GetBlockGridItemAreasHtmlAsync(Model)

Stylesheet

Using the default rendering together with your layout stylesheet will provide what you need for rendering the layout.

If you like to use the Default Layout Stylesheet, you must copy the stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the CSS folder, example: wwwroot/css/umbraco-blockgridlayout.css.

<link rel="stylesheet" href="@Url.Content("~/css/blockgridlayout.css")" />

A set of built-in Partial Views are responsible for rendering the Blocks and Areas in a grid layout. If you want to tweak or change the way the grid layout is rendered, you can use the built-in Partial Views as a template:

Clone the views from <a href="https://github.com/umbraco/Umbraco-CMS/">GitHub</a>. They can be found in /src/Umbraco.Cms.StaticAssets/Views/Partials/blockgrid/
Copy the cloned views to the local folder Views/Partials/blockgrid/
Make changes to your copied views. The entry point for GetBlockGridHtmlAsync() is the view default.cshtml

2. Build your own rendering

The built-in value converter for the Block Grid property editor lets you use the block data as you like. Call the Value<T> method with a type of BlockGridModel to have the stored value returned as a BlockGridModel instance.

BlockGridModel contains the Block Grid configuration (like the number of columns as GridColumns) whilst also being an implementation of IEnumerable<BlockGridItem> (see details for BlockGridItem above).

The following example mimics the built-in rendering mechanism for rendering Blocks using Partial Views:

View.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@using Umbraco.Cms.Core.Models.Blocks
@{
    var grid = Model.Value<BlockGridModel>("myGrid");

    // get the number of columns defined for the grid
    var gridColumns = grid.GridColumns;

    // iterate the block items
    foreach (var item in grid)
    {
        var content = item.Content;

        @await Html.PartialAsync("PathToMyFolderOfPartialViews/" + content.ContentType.Alias, item);
    }
}

If you do not want to use Partial Views, you can access the block item data directly within your rendering:

View.cshtml

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@using Umbraco.Cms.Core.Models.Blocks
@{
    var grid = Model.Value<BlockGridModel>("myGrid");

    // get the number of columns defined for the grid
    var gridColumns = grid.GridColumns;

    // iterate the block items
    foreach (var item in grid)
    {
        // get the content and settings of the block
        var content = item.Content;
        var settings = item.Settings;
        // get the areas of the block
        var areas = item.Areas;
        // get the dimensions of the block
        var rowSpan = item.RowSpan;
        var columnSpan = item.ColumnSpan;
        // get forced placement of the block
        var forceLeft = item.ForceLeft;
        var forceRight = item.ForceRight;

        // render the block data
        <div style="background-color: #@(settings.Value<string>("color"))">
            <h2>@(content.Value<string>("title"))</h2>
            <span>This block is supposed to span <b>@rowSpan rows</b> and <b>@columnSpan columns</b></span>
        </div>
    }
}

Write a Custom Layout Stylesheet

The default layout stylesheet is using CSS Grid. This can be modified to fit your implementation and your project.

Adjusting the Default Layout Stylesheet

To make additions or overwrite parts of the default layout stylesheet, import the default stylesheet at the top of your own file.

@import 'css/umbblockgridlayout.css';

You need to copy the Default Layout Stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the CSS folder, example: wwwroot/css/umbraco-blockgridlayout.css.

Write a new Layout Stylesheet

In this case, you would have to write the layout from scratch.

You are free to pick any style, meaning there is no requirement to use CSS Grid. It is, however, recommended to use CSS Grid to ensure complete compatibility with the Umbraco backoffice.

CSS Class structure and available data

When extending or writing your own layout, you need to know the structure and what data is available.

For example: You can use the below HTML structure:

<div class="umb-block-grid"
     style="--umb-block-grid--grid-columns: 12;"
>

    <!-- Notice this is the same markup used every time we will be printing a list of blocks: -->
    <div class="umb-block-grid__layout-container">

        <!-- repeated for each layout entry -->
        <div
            class="umb-block-grid__layout-item"
            data-content-element-type-alias="MyElementTypeAlias"
            data-content-element-type-key="00000000-0000-0000-0000-000000000000"
            data-element-udi="00000000-0000-0000-0000-000000000000"
            data-col-span="6"
            data-row-span="1"
            ?data-force-left
            ?data-force-right
            style="
            --umb-block-grid--item-column-span: 6;
            --umb-block-grid--item-row-span: 1;
            "
        >

            <!-- Here the Razor View or Custom View for this block will be rendered. -->

            <!-- Each razor view must render the 'area-container' them self.
            This can be done by the Razor helper method:

            @await Html.GetBlockGridItemAreasHtmlAsync(Model)

            The structure will be as printed below,
            Do notice targeting the 'area-container' needs a double selector as markup will be different in Backoffice.
            Here is an example of the CSS selector:
                .umb-block-grid__area-container, .umb-block-grid__block--view::part(area-container) {
                    position: relative;
                }
            -->
            <div
                class="umb-block-grid__area-container"
                style="--umb-block-grid--area-grid-columns: 9;"
            >

                <!-- repeated for each area for this block type. -->
                <div
                    class="umb-block-grid__area"
                    data-area-col-span="3"
                    data-area-row-span="1"
                    data-area-alias="MyAreaAlias"
                    style="
                    --umb-block-grid--grid-columns: 3;
                    --umb-block-grid--area-column-span: 3;
                    --umb-block-grid--area-row-span: 1;
                    ">

                        <!-- Notice here we print the same markup as when we print a list of blocks(same as the one in the root of this structure..):
                        <div class="umb-block-grid__layout-container">
                            ...
                        </div>
                        End of notice.  -->
                </div>
                <!-- end of repeat -->

            </div>


        </div>
        <!-- end of repeat -->

    </div>

</div>

Build a Custom Backoffice View

Building Custom Views for Block representations in Backoffice is based on the same API for all Block Editors.

Read about building a Custom View for Blocks here

Creating a Block Grid programmatically

In this example, we will be creating content programmatically for a "spot" Blocks in a Block Grid.

On a document type add a property called blockGrid.
Then add as editor Block Grid.
In the Block Grid add a new block and click to Create new Element Type
Name this element type spotElement with the following properties:

a property called title with the editor of Textstring
a property called text with the editor of Textstring

Then on the Settings model click to add a new Setting.
Then click to Create new Element Type.
Name this element type spotSettings with the following properties:

a property called featured with the editor of True/false.

The raw input data for the spots looks like this:

new[]
{
    new { Title = "Item one", Text = "This is item one", Featured = false, ColumnSpan = 12, RowSpan = 1, ForceLeft = false, ForceRight = false },
    new { Title = "Item two", Text = "This is item two", Featured = true, ColumnSpan = 6, RowSpan = 2, ForceLeft = false, ForceRight = false }
}

The resulting JSON object stored for the Block Grid will look like this:

{
    "layout": {
        "Umbraco.BlockGrid": [{
                "contentUdi": "umb://element/bb23fe28160941efa506da7aa314172d",
                "settingsUdi": "umb://element/9b832ee528464456a8e9a658b47a9801",
                "areas": [],
                "columnSpan": 12,
                "rowSpan": 1,
                "forceLeft": false,
                "forceRight": false
            }, {
                "contentUdi": "umb://element/a11e06ca155d40b78189be0bdaf11c6d",
                "settingsUdi": "umb://element/d182a0d807fc4518b741b77c18aa73a1",
                "areas": [],
                "columnSpan": 6,
                "rowSpan": 2,
                "forceLeft": false,
                "forceRight": false
            }
        ]
    },
    "contentData": [{
            "contentTypeKey": "0e9f8609-1904-4fd1-9801-ad1880825ff3",
            "udi": "umb://element/bb23fe28160941efa506da7aa314172d",
            "title": "Item one",
            "text": "This is item one"
        }, {
            "contentTypeKey": "0e9f8609-1904-4fd1-9801-ad1880825ff3",
            "udi": "umb://element/a11e06ca155d40b78189be0bdaf11c6d",
            "title": "Item two",
            "text": "This is item two"
        }
    ],
    "settingsData": [{
            "contentTypeKey": "22be457c-8249-42b8-8685-d33262f7ce2a",
            "udi": "umb://element/9b832ee528464456a8e9a658b47a9801",
            "featured": "0"
        }, {
            "contentTypeKey": "22be457c-8249-42b8-8685-d33262f7ce2a",
            "udi": "umb://element/d182a0d807fc4518b741b77c18aa73a1",
            "featured": "1"
        }
    ]
}

For each item in the raw data, we need to create:

One contentData entry with the title and text.
One settingsData entry with the featured value (the checkbox expects "0" or "1" as data value).
One layout entry with the desired column and row spans.

All contentData and layoutData entries need their own unique Udi as well as the ID (key) of their corresponding Element Types. In this sample, we only have one Element Type for content (spotElementType) and one for settings (spotSettingsType). In a real life scenario, there could be any number of Element Type combinations.

First and foremost, we need models to transform the raw data into Block Grid compatible JSON. Create a class called Model.cs containing the following:

Models.cs

using Newtonsoft.Json;
using Umbraco.Cms.Core;

namespace My.Site.Models;

// this is the "root" of the block grid data
public class BlockGridData
{
    public BlockGridData(BlockGridLayout layout, BlockGridElementData[] contentData, BlockGridElementData[] settingsData)
    {
        Layout = layout;
        ContentData = contentData;
        SettingsData = settingsData;
    }

    [JsonProperty("layout")]
    public BlockGridLayout Layout { get; }

    [JsonProperty("contentData")]
    public BlockGridElementData[] ContentData { get; }

    [JsonProperty("settingsData")]
    public BlockGridElementData[] SettingsData { get; }
}

// this is a wrapper for the block grid layout, purely required for correct serialization
public class BlockGridLayout
{
    public BlockGridLayout(BlockGridLayoutItem[] layoutItems) => LayoutItems = layoutItems;

    [JsonProperty("Umbraco.BlockGrid")]
    public BlockGridLayoutItem[] LayoutItems { get; }
}

// this represents an item in the block grid layout collection
public class BlockGridLayoutItem
{
    public BlockGridLayoutItem(Udi contentUdi, Udi settingsUdi, int columnSpan, int rowSpan, bool forceLeft, bool forceRight)
    {
        ContentUdi = contentUdi;
        SettingsUdi = settingsUdi;
        ColumnSpan = columnSpan;
        RowSpan = rowSpan;
        ForceLeft = forceLeft;
        ForceRight = forceRight;
    }

    [JsonProperty("contentUdi")]
    public Udi ContentUdi { get; }

    [JsonProperty("settingsUdi")]
    public Udi SettingsUdi { get; }

    [JsonProperty("areas")]
    // areas are omitted from this sample for abbreviation
    public object[] Areas { get; } = { };

    [JsonProperty("columnSpan")]
    public int ColumnSpan { get; }

    [JsonProperty("rowSpan")]
    public int RowSpan { get; }

    [JsonProperty("forceLeft")]
    public bool ForceLeft { get; }

    [JsonProperty("forceRight")]
    public bool ForceRight { get; }

}

// this represents an item in the block grid content or settings data collection
public class BlockGridElementData
{
    public BlockGridElementData(Guid contentTypeKey, Udi udi, Dictionary<string, object> data)
    {
        ContentTypeKey = contentTypeKey;
        Udi = udi;
        Data = data;
    }

    [JsonProperty("contentTypeKey")]
    public Guid ContentTypeKey { get; }

    [JsonProperty("udi")]
    public Udi Udi { get; }

    [JsonExtensionData]
    public Dictionary<string, object> Data { get; }
}

By injecting ContentService and ContentTypeService into an API controller, we can transform the raw data into Block Grid JSON. It can then be saved to the target content item. Create a class called BlockGridTestController.cs containing the following:

BlockGridTestController.cs

using Microsoft.AspNetCore.Mvc;
using My.Site.Models;
using Newtonsoft.Json;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Web.Common.Controllers;

namespace My.Site.Controllers;

public class BlockGridTestController : UmbracoApiController
{
    private readonly IContentService _contentService;
    private readonly IContentTypeService _contentTypeService;

    public BlockGridTestController(IContentService contentService, IContentTypeService contentTypeService)
    {
        _contentService = contentService;
        _contentTypeService = contentTypeService;
    }

    // POST: /umbraco/api/blockgridtest/create
    [HttpPost]
    public ActionResult Create()
    {
        // get the item content to modify
        IContent? content = _contentService.GetById(1203);
        if (content == null)
        {
            return NotFound("Could not find the content item to modify");
        }

        // get the element types for spot blocks (content and settings)
        IContentType? spotContentType = _contentTypeService.Get("spotElement");
        IContentType? spotSettingsType = _contentTypeService.Get("spotSettings");
        if (spotContentType == null || spotSettingsType == null)
        {
            return NotFound("Could not find one or more content types for block data");
        }

        // this is the raw data to insert into the block grid
        var rawData = new[]
        {
            new { Title = "Item one", Text = "This is item one", Featured = false, ColumnSpan = 12, RowSpan = 1, ForceLeft = false, ForceRight = false },
            new { Title = "Item two", Text = "This is item two", Featured = true, ColumnSpan = 6, RowSpan = 2, ForceLeft = false, ForceRight = false }
        };

        // build the individual parts of the block grid data from the raw data
        var layoutItems = new List<BlockGridLayoutItem>();
        var spotContentData = new List<BlockGridElementData>();
        var spotSettingsData = new List<BlockGridElementData>();
        foreach (var data in rawData)
        {
            // generate new UDIs for block content and settings
            var contentUdi = Udi.Create(Constants.UdiEntityType.Element, Guid.NewGuid());
            var settingsUdi = Udi.Create(Constants.UdiEntityType.Element, Guid.NewGuid());

            // create a new layout item
            layoutItems.Add(new BlockGridLayoutItem(contentUdi, settingsUdi, data.ColumnSpan, data.RowSpan, data.ForceLeft, data.ForceRight));

            // create new content data
            spotContentData.Add(new BlockGridElementData(spotContentType.Key, contentUdi, new Dictionary<string, object>
            {
                { "title", data.Title },
                { "text", data.Text },
            }));

            // create new settings data
            spotSettingsData.Add(new BlockGridElementData(spotSettingsType.Key, settingsUdi, new Dictionary<string, object>
            {
                { "featured", data.Featured ? "1" : "0" },
            }));
        }

        // construct the block grid data from layout, content and settings
        var blockGridData = new BlockGridData(
            new BlockGridLayout(layoutItems.ToArray()),
            spotContentData.ToArray(),
            spotSettingsData.ToArray());

        // serialize the block grid data as JSON and save it to the "blockGrid" property on the content item
        var propertyValue = JsonConvert.SerializeObject(blockGridData);
        content.SetValue("blockGrid", propertyValue);
        _contentService.Save(content);

        return Ok("Saved");
    }
}

For the above code IContent? content = _contentService.GetById(1203); change the id with your content node that is using the Block Grid.

In order to test this implementation, run the project and add /umbraco/api/blockgridtest/create after your domain name. If the result shows as Saved then check your content node and you will see the 2 spotElement contents.

This can also be tested via Postman as well if preffered.