Alias: Umbraco.ListView

Returns: IEnumerable<IPublishedContent>

Collection displays a collection of categories when it is enabled on a Document Type with children.

Enable collection

If enabled, editors will be able to see multiple children from a collection on a content node that has children. When not enabled, no collection 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 collection. If you set it to 5, then only 5 content items will be shown in the collection.

Order By

Will sort your collection 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 collection 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 collection, 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 you want to display, define what its name should be and what kind of value it should display. You can also move the headers around, re-ordering how they 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

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

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

• Allow bulk publish - content only

• Allow bulk unpublish - content only

• Allow bulk copy - content only

• Allow bulk move

• Allow bulk delete

Workspace View icon

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

Workspace View name

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

Show Content Workspace View First

Enable this to show the Content Workspace View by default instead of the collection's.

Content Example

Generic field value

The {{ value }} will take the value of the Email property and display it in the collection, 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.

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 collection setting.

Other examples

Alias: Umbraco.MultiNodeTreePicker

Returns: IEnumerable<IPublishedContent>

The Content Picker enables choosing the type of content tree to display and which specific part to render. It also allows you to set a dynamic root node for the content based on the current document using the Content Picker.

Data Type Definition Example

Minimum/maximum number of items

Define a limit on the number of items allowed to be selected.

Ignore user start nodes

Checking this field allows users to choose nodes they normally cannot access.

Node Type

This option allows for configuring what type of content is available when using the Data Type. The available types of content are Content, Members, or Media items.

When selecting Content from the dropdown, the option to specify a root node, also called the origin, becomes available.

When picking the origin there are several different options available:

The following options are available when picking the origin:

• Root: The root is the first level item of the sub-tree of the current node.

• Parent: The parent is the nearest ancestor of the current node.

• Current: The current node.

  • A picker that uses the current node, cannot pick anything when the current node is created, as it will not have any children.

• Site: The nearest ancestor of the current node with a domain assigned.

• Specific node: A specific node selected from the existing content.

When an origin has been specified, it becomes possible to continue to build a Dynamic Root by adding additional query steps.

Navigate the content tree relative to the specified origin to execute multiple query steps and find the root node needed.

The following options are available:

• Nearest Ancestor or Self: Find the nearest ancestor or current item that fits with one of the configured Document Types.

• Furthest Ancestor or Self: Find the furthest ancestor or current item that fits with one of the configured Document Types.

• Nearest Descendant or Self: Find the nearest descendant or current item that fits with one of the configured Document Types.

• Furthest Descendant or Self: Find the furthest descendant or current item that fits with one of the configured Document Types.

The options above are all based on navigating the document hierarchy by locating ancestors and descendants. It is possible to execute custom steps to build even more complex queries. Once a custom query is available it will be added to the bottom of the Append steps to query dialog. Learn more about adding custom query steps in the section below.

Each query step takes the output from the origin or the previous step as input. It is only ever the result of the last query step that is passed to the next step.

Adding a custom query step

Custom query steps can be used to solve specific use cases, such as traversing sibling documents or matching property values. Before the custom query steps can be selected in the Data Type settings, they must be defined via code.

When implementing a query step it requires a collection of origins and information about the query step. The collection is taken from where the name specified in the UI can be found.

You can inject dependencies into the constructor. These dependencies could be custom repositories or the IVariationContextAccessor, if you want to use the current culture.

The ExecuteAsync method receives a set of content keys from the last executed query step or the origin. It has to return a new set of content keys.

public class MyCustomDynamicRootQueryStep : IDynamicRootQueryStep
{
    private readonly IMyCustomRepository _myCustomRepository;

    public MyCustomDynamicRootQueryStep(IMyCustomRepository myCustomRepository)
    {
        _myCustomRepository = myCustomRepository;
    }

    public async Task<Attempt<ICollection<Guid>>> ExecuteAsync(ICollection<Guid> origins, DynamicRootQueryStep filter)
    {
        // The string below is what you specify in the UI to execute this custom query step.
        if (filter.Alias != "MyCustom")
        {
            return Attempt<ICollection<Guid>>.Fail();
        }

        if (origins.Any() is false)
        {
            return Attempt<ICollection<Guid>>.Succeed(Array.Empty<Guid>());
        }

        // Replace the following with your custom logic
        var result = await _myCustomRepository.GetWhateverIWantAsync(origins);

        return Attempt<ICollection<Guid>>.Succeed(result);
    }
}

To register the custom query step, append it to the existing query steps, DynamicRootSteps(). This is done from a composer as shown below.

public class CustomQueryStepComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DynamicRootSteps().Append<MyCustomDynamicRootQueryStep>();
    }
}

Allow items of type

Choose which types of content should be available to pick using the Content Picker.

This is done by selecting one or more Document Types.

Query Example

Consider the following tree structure where the Document Type alias is presented in square brackets.

• Codegarden

  • 2023 [year]

    • Talks [talks]

      • ...

      • Umbraco anno MMXXIII [talk]

    • Stages [stages]

      • Social Space [stage]

      • No 10 [stage]

      • No 16 [stage]

      • The Theatre [stage]

  • 2022 [year]

    • Talks [talks]

      • ...

    • Stages [stages]

      • Main Stage [stage]

      • The Barn [stage]

      • The Theatre [stage]

Consider configuring a Content Picker on the talk Document Type to select a stage for the talk. Here, you want to display only the stages for the actual year. To do this, you need to set the parent as the origin.

For instance, if you are on the Umbraco anno MMXXIII node, the collection of content keys passed into the first query step will only contain the Talks content node.

• First, query for the nearest ancestors of the type year. This will return 2023.

• Second, query for the nearest descendants of the type stages.

When opening the picker on the Umbraco anno MMXXIII node, it will now show the children of the node on the path Codegarden > 2023 > Stages.

MVC View Example

Without Modelsbuilder

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

With Modelsbuilder

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically. To update the 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 Content Picker
    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));
}

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);
}

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);
}

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 Media Picker Property Editor.

Settings

Define Crops

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

ImageSharp.Web is image processing middleware for ASP.NET.

We bundle this package with Umbraco and you can therefore take full advantage of all its features for resizing and format changing. Learn more about the built in processing commands in the official ImageSharp documentation.

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:

<img src="@Url.GetCropUrl(Model.Photo,"square", true)" />

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"

<img src="@Url.GetCropUrl(Model.SecondaryPhoto, "customCropper", "banner")" />

Or, alternatively using the MediaWithCrops extension method:

<img src="@Model.SecondaryPhoto.GetCropUrl("customCropper", "banner")" />

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

@if (Model.Photo is not null)
{
    <img src="@Url.GetCropUrl(Model.Photo, height: 300, width: 400)" alt="@Model.Photo.Name" />
}

CSS background example to output a "banner" crop

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

@if (Model.Photo is not null)
{
    var cropUrl = Url.GetCropUrl(Model.Photo, "square", false);
    <style>
        .myCssClass {
            background-image: url("@cropUrl");
            height: 400px;
            width: 400px;
        }
    </style>
    <div class="product-image-container myCssClass"></div>
}

Add values programmatically

To update a content property value you need the Content Service.

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.

using Microsoft.AspNetCore.Mvc;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.PropertyEditors.ValueConverters;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;

namespace Umbraco.Docs.Samples.Web.Property_Editors_Add_Values;

[ApiController]
[Route("/umbraco/api/createimagecroppervalues")]
public class CreateImageCropperValuesController : Controller
{
    private readonly IContentService _contentService;
    private readonly IMediaService _mediaService;
    private readonly MediaUrlGeneratorCollection _mediaUrlGeneratorCollection;
    private readonly IJsonSerializer serializer;

    public CreateImageCropperValuesController(
        IContentService contentService,
        IMediaService mediaService,
        MediaUrlGeneratorCollection mediaUrlGeneratorCollection, IJsonSerializer serializer)
    {
        _contentService = contentService;
        _mediaService = mediaService;
        _mediaUrlGeneratorCollection = mediaUrlGeneratorCollection;
        this.serializer = serializer;
    }

    // /Umbraco/Api/CreateImageCropperValues/CreateImageCropperValues
    [HttpPost("createimagecroppervalues")]
    public ActionResult<bool> CreateImageCropperValues()
    {
        // Create a variable for the GUID of the page you want to update
        var contentKey = Guid.Parse("89974f8b-e213-4c32-9f7a-40522d87aa2f");

        // Get the page using the GUID you've defined
        IContent? content = _contentService.GetById(contentKey);
        if (content == null)
        {
            return false;
        }

        // Create a variable for the GUID of the media item you want to use
        var mediaKey = Guid.Parse("b6d4e98a-07c0-45f9-bfcc-52994f2806b6");

        // Get the desired media file
        IMedia? media = _mediaService.GetById(mediaKey);
        if (media == null)
        {
            return false;
        }

        // Create a variable for the image cropper and set the source
        var imageCropperValue = new ImageCropperValue
        {
            Src = media.GetUrl("umbracoFile", _mediaUrlGeneratorCollection)
        };

        // Serialize the image cropper value
        var propertyValue = serializer.Serialize(imageCropperValue);

        // Set the value of the property with alias "cropper"
        // - remember to add the "culture" parameter if "cropper" is set to vary by culture
        content.SetValue("cropper", propertyValue);

        return _contentService.Save(content).Success;
    }
}

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:

// Set the value of the "Cropper" property on content of type MyContentType
// - remember to add the "culture" parameter if "cropper" is set to vary by culture
content.SetValue(nameof(MyContentType.Cropper).ToFirstLowerInvariant(), propertyValue);

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:

public Dictionary<string, string> GetCropUrls(IPublishedContent image)
{
    // Get the Image Cropper property value for property with alias "umbracoFile"
    ImageCropperValue? imageCropperValue = image.Value<ImageCropperValue>("umbracoFile");
    if (imageCropperValue?.Crops == null)
    {
        return new Dictionary<string, string>();
    }

    // Return all crop aliases and their corresponding crop URLs as a dictionary
    var cropUrls = new Dictionary<string, string>();
    foreach (ImageCropperValue.ImageCropperCrop crop in imageCropperValue.Crops)
    {
        // Get the cropped URL and add it to the dictionary that I will return
        var cropUrl = crop.Alias != null
            ? image.GetCropUrl(crop.Alias)
            : null;
        if (cropUrl != null)
        {
            cropUrls.Add(crop.Alias!, cropUrl);
        }
    }

    return cropUrls;
}

Sample on how to change the format of the image

Below the example to output a PNG using ImageSharp.Web format command.

<img src="@Url.GetCropUrl(Model.Photo, 500, 300, furtherOptions: "&format=png")" />

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

Without labels

@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 colors on the Color Picker
    content.SetValue("color", "38761d");

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

With labels

@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 colors on the Color Picker
    content.SetValue("color", "{'value':'000000', 'label':'Black', 'sortOrder':1, 'id':'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;
@using Umbraco.Cms.Core.PublishedCache;
@{
    // Set the value of the property with alias 'color'
    content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.Color).Alias, "38761d");
}

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.

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.

@inject IContentService Services;
@using Umbraco.Cms.Core.Serialization
@using Umbraco.Cms.Core.Services;
@inject IJsonSerializer Serializer;
@{
    // 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", Serializer.Serialize(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, Serializer.Serialize(new[] { "Umbraco", "CodeGarden"}));
}

Returns: Date

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

Data Type Definition Example

Content Example

MVC View Example - displays a datetime

Typed

Dynamic (Obsolete)

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:

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.

Start node

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

Ignore 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

Content Example

MVC View Example

Multiple enabled without Modelsbuilder

Multiple enabled with Modelsbuilder

Multiple disabled without Modelsbuilder

Multiple disabled with Modelsbuilder

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:

Explicitly retrieving global crops

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

Add values programmatically

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

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:

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:

Alias: Umbraco.ContentPicker

Returns: IPublishedContent

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

Data Type Definition Example

Document Picker 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:

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:

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

If Max number of items is configured to 1

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:

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.

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

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:

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

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:

Alias: Umbraco.Tags

Returns: IEnumerable<string>

The Tags property editor allows you to add multiple tags to a node.

Data Type Definition Example

Tag group

The Tag group setting provides a way to categorize your tags in groups. So for each category you will create a new instance of the Tags property editor and setup the unique category name for each instance. Whenever a tag is added to an instance of the tags property editor it's added to the tag group, which means it will appear in the Typeahead list when you start to add another tag. Only tags that belong to the specified group will be listed. If you have a "Frontend" group and a "Backend" group the tags from the "Frontend" group will only be listed if you're adding a tag to the Tags property editor configured with the "Frontend" group name and vice versa.

Storage type

Data can be saved in either Comma-Separated Values (CSV) format or in JSON format. By default data is saved in JSON format. The difference between using CSV and JSON is that with JSON you can save a tag, which includes comma separated values.

Content Examples

CSV tags

JSON tags

Tags typeahead

Whenever a tag has been added it will be visible in the typeahead when you start typing on other pages.

MVC View Example - displays a list of tags

Multiple items - with Modelsbuilder

Multiple items - without Modelsbuilder

Setting Tags Programmatically

You can use the ContentService to create and update Umbraco content from c# code, when setting tags there is an extension method (SetTagsValue) on IContentBase that helps you set the value for a Tags property. Remember to add the using statement for Umbraco.Core.Models to take advantage of it.

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:

More on working with Tags

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.

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

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:

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:

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

With Modelsbuilder

Add values programmatically

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

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:

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:

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

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:

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:

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

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:

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

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:

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

Settings

Content Example

Without a character and rows limit

With a character limit and rows limit

MVC View Example

Without Modelsbuilder

With Modelsbuilder

Add value 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:

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

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:

Alias: Umbraco.TinyMCE

Returns: HTML

The Rich Text Editor (RTE) is based on and is highly configurable. Depending on the configuration, it will give your content editors more flexibility when working with content that should be more than only plain text.

Customize everything from toolbar options to editor size to where pasted images are saved.

Use CSS to define specific editor styles and add them as formatting options of the Rich Text Editor.

Use Blocks to define specific parts which can be added as part of the markup of the Rich Text Editor.

Extend the functionality of the Rich Text Editor with plugins.

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:

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.

Add options

Options are the values 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:

Configuration

In this article you can learn about the various ways you can configure the RTE.

Toolbar

You have full control over which options should be available on the RTE.

In the examble above, all 34 options have been enabled. The options include copy/paste buttons, font styles like bold and italics, bullet lists and options to embed videos and insert images.

Stylesheets

It is possible to define specific styles that can be used when editing content using the RTE. You can use as many of these styles with the RTE as you want.

Dimensions

Define height and width of the editor displayed in the content section.

Maximum size for inserted images

Define the maximum size for images added through the Rich Text Editor.

If inserted images are larger than the dimensions defined here, the images will be resized automatically.

Mode

The Rich Text Editor comes in two different modes: Classic and Inline.

Classic

The default mode which displays the toolbar at the top.

Inline

In this mode the toolbar is hidden, and only shows up when content in the editor is highlighted.

Blocks

Overlay Size

Select the width of the link picker overlay. The overlay size comes in three sizes: Small, Medium, and Large.

Hide Label

When this option is checked the label and description for the RTE property will be hidden.

Ignore User Start Nodes

Some of the backoffice users might be restricted to a specific part of the content tree. When the "Ignore User Start Nodes" is checked, the users can pick any piece of content from the content tree, when adding internal links through the RTE.

Image Upload Folder

Images added through the RTE is by default added to the root of the Media library.

Sometimes you might want to add the images to a specific folder. This folder can be configured using the "Image Upload Folder" setting.

It is possible to define specific styles and fonts for the Rich Text Editor (RTE). Once you have defined the styles, and enabled them on the RTE Data Type, the styles can be accessed directly in the Content section.

Creating RTE Styles

The RTE styles are created and managed in the Umbraco backoffice.

• Find the Stylesheets folder in the Settings section.

• Click ... next to the Stylesheets folder and select Create....

• Choose New Rich Text Editor style sheet file.

• Give the new stylesheet a name and Save it.

This will generate an empty CSS file in your project.

At this point, you can start adding specific styles, that your editors can then use in the Content section when creating and writing new content.

The image above is an example of how an RTE style can be configured. When working with these styles, the Preview feature will show you how the style will look when applied.

Every style you add, will automatically be added to the CSS file. The file will be placed in the same location as the rest of your CSS files. It is possible to edit the file directly from the backoffice as well. Access it from the Code tab in the top-right corner.

Using RTE Styles

In order for your editors to be able to use the styles when working with content, two things needs to be done.

1. Enable "Style select"

The styles will be accessed by the editors using the "Formats" dropdown in the toolbar of the RTE. In order the enable the dropdown, the "Style select" toolbar option needs to be checked.

2. Select the styles

You can have as many different styles for your RTEs as you want. You might want to have different styles for different RTE Data Types.

When configuring your RTE Data Types, you can select which stylesheets your content editors should be able to use.

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 Umbraco Flavored Markdown (UFM) syntax to display values of properties. Example: My Block {=myPropertyAlias} will be shown as: My Block FooBar.

Special variables

Currently, Umbraco 14.1 only supports rendering a block's content properties. Special variables like $index, $contentTypeName, $settings, and so on will be expanded in upcoming releases.

In the meantime, you can create your own custom UFM components. For more information, see the article. From there, you will be able to consume the UMB_BLOCK_ENTRY_CONTEXT to access the entire data of a block item.

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:

1. Navigate to the Settings section in the Umbraco backoffice.

2. Click ... next to the Data Types folder.

3. Select Create -> New Data Type.

4. 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:

• 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 Block Grid. 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

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

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.

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

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

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.

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

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:

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

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

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.Cms.Core.Models.Blocks.BlockGridItem. This model contains Content and Settings from your block, as well as the configured RowSpan, ColumnSpan, 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:

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.Cms.Core.Models.Blocks.BlockGridItem.

Putting it all together

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

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:

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.

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:

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

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.

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:

Build a Custom Backoffice View

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

Creating a Block Grid programmatically

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

1. On a Document Type add a property called blockGrid.

2. Then add as editor Block Grid.

3. In the Block Grid add a new block and click to Create new Element Type

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

1. Then on the Settings model click to add a new Setting.

2. Then click to Create new Element Type.

3. 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:

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

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 (spotElement) and one for settings (spotSettings). In a real life scenario, there could be any number of Element Type combinations.

1. 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:

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

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

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

Umbraco CMS currently ships with two Block Editors: the Block List and the Block Grid.

Customizing Block Editors

Learn how to create custom views for the blocks used in your Block Grid or Block List property editors.

Get an overview of available configurations for the label properties.

Overview

The Rich Text Editor (RTE) in Umbraco is based on the open source editor . TinyMCE is a highly customizable editor, and it is possible to extend the functionality of the editor by adding plugins.

TinyMCE comes with a lot of plugins out of the box, but it is also possible to create your own plugins. This article will show you how to add a custom plugin to the rich text editor.

Open-Source Plugins

TinyMCE has a lot of open-source plugins available. You can find a list of these plugins on the .

Premium Plugins

TinyMCE also has a number of available. These plugins are only available for . They can be added to the rich text editor by .

Adding a Plugin

To enable plugins in the rich text editor, you need to add an extension type called tinyMcePlugin in a manifest file. The manifest file is a JSON file that describes the plugin and how it should be loaded. You can add a plugin such as the open source to the rich text editor. You can also define your own custom plugin to extend the functionality of the editor. This way you can add custom buttons, dialogs, or other features to the editor.

Creating a Custom Plugin

Examples

Load a custom plugin that gives you the ability to interact with the global tinymce editor object.

Here we are loading a custom plugin called myrteplugin and adding a button to the editor called myrtebutton. When the button is clicked, it will insert the text Hello World! into the editor.

1.Add a manifest file

First we create an umbraco-package.json file which will contain the manifest for the plugin. This adds a button to the toolbar in the rich text editor, which editors can enable on the Data Type. We are also letting the rich text editor know it should load the plugin from the plugin.js file.

2.Add the plugin.js file

The plugin.js file should contain the JavaScript code for the plugin. The file is loaded as a JavaScript module and must export a default class that extends the UmbTinyMcePluginBase class.

The button must be added to the toolbar in the rich text editor configuration.

You can go to any Document Type that uses the rich text editor and click the button to insert the text Hello World! after.

You have full access to the tinymce editor object, so you can create any custom functionality you need.

Learn more

Adding a premium plugin

To add a premium plugin, you need to add the plugin name to the plugins array in the config object of a tinyMcePlugin extension. You also need to add a JavaScript module that can load up the cloud-hosted TinyMCE premium plugins bundle.

1.Declaring the plugin

2.Creating the plugin.js file

The plugin.js file should contain the JavaScript code to load the cloud-hosted TinyMCE premium plugins bundle. You must replace {Cloud API Key} with your own Cloud API key.

We have now enabled the powerpaste plugin. We have configured it to allow pasting in local images. It will prompt when pasting Word documents, but for HTML documents it will clean the HTML without prompting.