Property Editors

A Property Editor is the editor that a Data Type references. A Data Type is defined by a user in the Umbraco backoffice and references a Property Editor. In Umbraco a Property Editor is defined in a JSON manifest file and associated JavaScript files.

When creating a Data Type, you specify the property editor for the Data Type to use by selecting from the "Property editor" list (as shown below).

Umbraco comes pre-installed with many useful property editors. Go to child articles to read about each.

Checkbox

Returns: Boolean

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

Data Type Definition Example

The Checkbox 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

@{
    if (!Model.Value<bool>("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.

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

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

Checkbox List

Alias: Umbraco.CheckBoxList

Returns: IEnumerable<string>

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

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

Data Type Definition Example

Content Example

MVC View Example

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

@using Newtonsoft.Json
@{
    // Get access to ContentService
    var contentService = Services.ContentService;

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

Color Picker

Alias: Umbraco.ColorPicker

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

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

Data Type Definition Example

Content Example

Example

@using Umbraco.Core.PropertyEditors.ValueConverters
@{
    var hexColor = Model.Value("Color");
    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.

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

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

Content Picker

Alias: Umbraco.ContentPicker

Returns: IPublishedContent

The content picker opens a panel to pick a specific page from the content structure.

Data Type Definition Example

Content Example

MVC View Example

@{
    IPublishedContent typedContentPicker = Model.Value<IPublishedContent>("featurePicker");
    if (typedContentPicker != null)
    {
        <p>@typedContentPicker.Name</p>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

    // 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 page you want to assign to the content picker 
    var page = Umbraco.Content("665d7368-e43e-4a83-b1d4-43853860dc45");
    
    // Create an Udi of the page
    var udi = Udi.Create(Constants.UdiEntityType.Document, page.Key);

    // Set the value of the property with alias 'featurePicker'. 
    content.SetValue("featurePicker", 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:

@{
    // Set the value of the property with alias 'featurePicker'
    content.SetValue(Home.GetModelPropertyType(x => x.FeaturePicker).Alias, udi.ToString());
}

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

@Model.Value("datePicker")

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

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

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

@Model.Value("MyDecimal")

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

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

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

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

Multiple items

@if (Model.HasValue("categories"))
{
    var categories = Model.Value<IEnumerable<string>>("categories");
    <ul>
        @foreach (var category in categories)
        {
            <li>@category</li>
        }
    </ul>
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

@using Newtonsoft.Json
@{
    // Get access to ContentService
    var contentService = Services.ContentService;

    // 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 'categories'. 
    content.SetValue("categories", JsonConvert.SerializeObject(new[] { "News" }));

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

Email Address

Alias: Umbraco.EmailAddress

Returns: String

Displays an email address.

Settings

Data Type Definition Example

Content Example

MVC View Example

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

Add value programmatically

See the example below to learn how a value can be added or changed programmatically to an Email-address property.

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

    // 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", "stk@umbraco.com");

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

The value sent to an EmailAddress property needs to be a correct email address, e.g. 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.

File upload

Alias: Umbraco.UploadField

Returns: string

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

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

@{
    if (Model.Value<string>("myFile").HasValue())
    {
        var myFile = Model.Value<string>("myFile");

        <a href="@myFile">@Path.GetFileName(myFile)</a>
    }

}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

    // Create a variable for the GUID of the parent where you want to add a child item
    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 file you want to upload, in this case the Our Umbraco logo
    var imageUrl = "https://our.umbraco.com/assets/images/logo.svg";

    // Create a request to get the file
    var request = WebRequest.Create(imageUrl);
    var webResponse = request.GetResponse();
    var responseStream = webResponse.GetResponseStream();

    // Get the file name 
    var lastIndex = imageUrl.LastIndexOf("/", StringComparison.Ordinal) + 1;
    var filename = imageUrl.Substring(lastIndex, imageUrl.Length - lastIndex);

    // Create a media file
    var media = mediaService.CreateMediaWithIdentity("myImage", -1, "File");
    media.SetValue(Services.ContentTypeBaseServices, "umbracoFile", filename, responseStream);

    // Save the created media 
    mediaService.Save(media);

    // Get the published version of the media (IPublishedContent)
    var publishedMedia = Umbraco.Media(media.Id);

    // Set the value of the property with alias 'myFile' 
    content.SetValue("myFile", publishedMedia.Url());

    // Save the child item
    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); 
}

Image Cropper

Returns: JSON

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

Settings

Prevalues

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

Data Type Definition Example

Content Example

Provides a UI to upload an image, set a focal point on the image, and optionally crop and scale the image to predefined crops. By default, images in the cropper will be shown based on a set focal point, and only use specific crops if they are available.

The cropper comes in 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. Click it to upload an image.

Set focal point

By default, the cropper allows the editor to set a focal point on the uploaded image. Next to the image, all the preset crops are shown to give the editor a preview of what the image will look like to the end user.

Crop and resize

If needed, the editor can crop the image to specific crop presets, to ensure the right part and size of the image is shown for a specific crop.

Sample code

Image Cropper comes with an API to generate crop URLs, or you can access its raw data directly as a dynamic object.

The Url Helper method can be used to replace the IPublishedContent extension methods. It has a set of extensions for working with URLs.

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

@Url.​GetCropUrl​(mediaItem: Model.Image, cropAlias: ​"Grid"​, htmlEncode: true);

HtmlEncode is by default set to true, which means you only need to define the parameter if you wan't to disable HTML encoding.

MVC View Example to output a "banner" crop from a cropper property with the alias "image"

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

Or, alternatively:

<img src="@(Model.Image.GetCropUrl("banner", Current.ImageUrlGenerator))" />

MVC View Example to output create custom crops - in this case forcing a 300 x 400 px image

@if (Model.HasValue("image"))
{
    <img src="@Model.Image.GetCropUrl(height: 300, width: 400, imageUrlGenerator: Current.ImageUrlGenerator)" />
}

CSS background example to output a "banner" crop from a cropper property with alias "image"

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

@{
    
    if (Model.Image != null)
    {
        var cropUrl = Url.GetCropUrl(Model.Image, "banner", false);
        <style>
            .myCssClass {
                background-image: url("@cropUrl");
            }
        </style>
    }
}

Upload property replacement

You can replace an upload property with a cropper, existing images will keep returning their current path and work unmodified with the cropper applied. The old image will even be available in the cropper, so you can modify it if you ever need to.

However, be aware that a cropper returns a dynamic object when saved, so if you perform any sort of string modifications on your upload property value, you will most likely see some errors in your templates / macros.

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

@using Umbraco.Core.PropertyEditors.ValueConverters
@using Newtonsoft.Json
@{
    // Get access to ContentService
    var contentService = Services.ContentService;
    
    // 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 media item you want to use
    var mediaKey = Guid.Parse("8835014f-5f21-47b7-9f1a-31613fef447c");

    // Get the desired media file
    var media = Umbraco.Media(mediaKey);

    // Create a variable for the image cropper and set the source 
    var cropper = new ImageCropperValue {Src = media.Url()};

    // Serialize the image cropper value 
    var cropperValue = JsonConvert.SerializeObject(cropper);

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

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

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: Decimal, Date/time, Time, Integer and Big integer.

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

Content Example

MVC View Example

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

    // 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 'pageLabel'. 
    content.SetValue("pageLabel", "A pre-set string value");

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

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

This example uses a generic field on a child item and displays it in the list.

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.

This will take the value picked up by the member picker.

And display it in the listview. Shown in the example below:

Other examples

Media 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 setting to overrule user permissions, to enable any user of this property to pick any Media Item of the choosen 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.

Content Example

MVC View Example

Multiple enabled

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

Multiple disabled

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

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

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

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

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

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

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

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

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

@using Umbraco.Web.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.Web.Models
@{
    var link = Model.Value<Link>("link");
    if (link != null)
    {
    <li><a href="@link.Url" target="@link.Target">@link.Name</a></li>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

@using Newtonsoft.Json
@using Umbraco.Web.Models
@{
    // Get access to ContentService
    var contentService = Services.ContentService;

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

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

@{
    var typedMultiNodeTreePicker = Model.Value<IEnumerable<IPublishedContent>>("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.

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

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

Nested Content

Alias: Umbraco.NestedContent

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

Nested Content is a list editing property editor, using Document 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.

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.
  • 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 doc 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 doc type using your new data type and you are set to start editing.

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:

@inherits Umbraco.Web.Mvc.UmbracoViewPage
@{
    var items = Model.Value<IEnumerable<IPublishedElement>>("myPropertyAlias");

    foreach(var item in items)
    {
        // Render your content, e.g. item.Value<string>("heading")
    }
}

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

Example:

@inherits Umbraco.Web.Mvc.UmbracoViewPage
@{
    var items = Model.Value<IEnumerable<IPublishedElement>>("myPropertyAlias");

    foreach(var item in items)
    {
        var description = item.Value<string>("description");
        var image = item.Value<IPublishedContent>("image");

        <h3>@item.GetProperty("heading").Value()</h3>

        if (!string.IsNullOrEmpty(description))
        {
            <p>@Html.Raw(Html.ReplaceLineBreaksForHtml(description))</p>
        }

        if (image != null)
        {
            <img src="@image.Url" alt="" />
        }
    }
}

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:

@inherits Umbraco.Web.Mvc.UmbracoViewPage
@{
    var item = Model.Value<IPublishedElement>("myPropertyAlias");
}
<h3>@item.Value("heading")</h3>

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.

 //if the class containing our code inherits SurfaceController, UmbracoApiController, 
 //or UmbracoAuthorizedApiController, we can get ContentService from Services namespace
 var contentService = Services.ContentService; 
//here we create a new node, and fill out attendeeList afterwards
 IContent request = ContentService.Create("new node", guid, "mydoctype", -1); 
 //our list which will contain nested content
 var attendees = new List<Dictionary<string, string>>(); 
//participants is our list of attendees - multiple items, good use case for nested content
 foreach (var person in participants) 
            attendees.Add(new Dictionary<string, string>() {
            //this is the only "default" value we need to fill for nested item
            {"ncContentTypeAlias","attendee"}, 
            {"user_name", person.name},
            {"user_email",person.user_email},
            {"join_time",person.join_time.ToString()}, 
            //we convert some properties to String just to be on the safe side
            {"leave_time",person.leave_time.ToString()},
            {"duration",person.duration.ToString()},
            {"phone",person.phone.ToString()}
            });
            }
            //bind the attendees List to attendeeList property on the newly created content node
            request.SetValue("attendeeList", JsonConvert.SerializeObject(attendees)); 
            //Save the entire node via ContentService
            ContentService.SaveAndPublish(request);

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.

@{
    int students = Model.HasValue("students") ? Model.Value<int>("students") : 0;
    int teachers = Model.HasValue("teachers") ? Model.Value<int>("teachers") : 0;
    int totalTravellers = students + teachers;

    <p>@totalTravellers</p>
}

Rendering the output casting to a string

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

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

    // 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 'students'
    content.SetValue("students", 20);
    
    // 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); 
}

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

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

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

    // 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 'colorTheme'
    content.SetValue("colorTheme", "water");
            
    // 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); 
}

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

@{
    if (Model.Value<string[]>("keyFeatureList").Length > 0)
    {
        <ul>
            @foreach (var item in Model.Value<string[]>("keyFeatureList"))
            {
                <li>@item</li>
            }
        </ul>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

    // 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 'keyFeatureList'
    content.SetValue("keyFeatureList", "Awesome" + Environment.NewLine + "Super");

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

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:

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

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

@if (Model.HasValue("singleValueSlider"))
{
    var value = Model.Value<decimal>("singleValueSlider");
    <p>@value</p>
}

@if (Model.HasValue("multiValueSlider"))
{
    var value = Model.Value<Umbraco.Core.Models.Range<decimal>>("multiValueSlider");
    <p>@(value.Minimum) and @(value.Maximum)</p>
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

With a range off

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

    // 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 'singleValueSlider'. 
    content.SetValue("singleValueSlider", 10);

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

With a range on

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

    // 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 desired value of the 'multiValueSlider' property
    var range = new Range<decimal> {Minimum = 10, Maximum = 12};

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

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

Tags

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

using GetProperty and Value

@if(Model.GetProperty("tags") !=null){
    <ul>
        @foreach(var tag in Model.GetProperty("tags").Value<IEnumerable<string>>()){
            <li>@tag</li>
        }
    </ul>
}

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.

using System.Web.Mvc;
using Umbraco.Core.Models;
using Umbraco.Web.Mvc;

namespace Our.Documentation.Examples.Controllers
{
    public class TestController : SurfaceController
    {
        // GET: Test
        public ActionResult Index()
        {
            //get content item to update
            IContent content = this.Services.ContentService.GetById(1234);

            // list of tags
            string[] newTagsToSet = new string[] { "Umbraco", "Example", "Setting Tags", "Helper" };

            //make content persisted
            Services.ContentService.Save(content);
            // set the tags
            content.AssignTags("aliasOfTagProperty", newTagsToSet);

            return View();
        }
    }
}

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

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

Add value programmatically

See the example below to learn how a value can be added or changed programmatically to a Textarea property.

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

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

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 500 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

@{
    // 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>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

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

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

Please note that getting the Value of the property will return the user ID - properties of the User can be accessed by referencing UserService.

@{
    if (Model.Value("userPicker") != null)
    {
        var us = Services.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>
    }
}

Add values programmatically

See the example below to see how a value can be added or changed programmatically.

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

    // 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); 
}
← Data TypesGrid Editors →