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

A section in Umbraco is where you perform specific tasks related to a particular area of Umbraco. For example, Content, Settings, and Users are all sections. You can navigate between the different sections by clicking the corresponding icon in the section menu positioned at the top of the Backoffice.

Below is a short overview of the default sections in Umbraco CMS:

Content

The Content section contains the content nodes that make up the website. Content is displayed as nodes in the Content tree.

Nodes in Umbraco can display the following content states:

• Grayed-out nodes are not published yet.

To create content, you must define it using Document Types.

For more information, see the Defining Content article.

Media

The Media section contains the media for the website. You can create folders and upload media files, such as images and PDFs. Additionally, you can customize the existing Media Types or define your own from the Settings section.

For more information, see the Creating Media article.

Settings

The Settings section allows you to manage website layout files, languages, media, and content types. It also gives you access to more advanced features such as the Log Viewer and extension insights.

The Settings section consists of:

Structure

• Document Types

• Media Types

• Member Types

• Data Types

• Languages

• Document Blueprints

Templating

• Templates (.cshtml files)

• Partial views (.cshtml files)

• Stylesheets (.css files)

• Scripts (.js files)

Advanced

• Relations

• Log Viewer

• Extension Insights

• Webhooks

The Settings section in the Umbraco backoffice has its own set of default dashboards.

For more information, see the Settings Dashboards article.

Packages

In this section, you can browse the different packages available for your Umbraco solution. You can also get an overview of all the packages you have installed or created.

For more information, see the Packages article.

Users

The Users section allows administrators to manage user accounts, assign permissions, set user roles, and monitor user activity within the backoffice. It provides control over who can access and modify content, media, and settings in the CMS.

For more information, see the Users article.

Members

The Members section allows to create and manage member profiles, set up member groups, and control Member's access to restricted content on the website.

For more information, see the Members article.

Dictionary

The Dictionary section is where you create and manage Dictionary Items. By managing these dictionary items, you can ensure consistent and efficient content translation and maintenance across different languages.

For more information, see the Dictionary Items article.

Add-Ons

To enhance Umbraco's functionality, you can integrate plugins and extensions tailored to specific needs. These add-ons expand Umbraco's capabilities, allowing for a more customized and powerful content management experience.

For example, you can start with core Umbraco features and later decide to integrate additional products. Currently, Umbraco supports add-on products like:

• Forms: Simplifies the creation and management of Forms.

• Deploy: Facilitates smooth deployment processes.

• Workflow: Enhances content workflows and approval processes.

• Commerce: Adds e-commerce capabilities to your site.

• UI Builder: Helps in designing and customizing the user interface.

When you add an add-on product to Umbraco, it appears in the Backoffice as a new section, seamlessly extending your content management capabilities.

If you wish to explore the unique features and use cases of Umbraco products, see the Exploring the Umbraco Products article.

For more information about extending the Umbraco platform through packages and integrations, see the Umbraco DXP documentation.

Help Section

The Help section in Umbraco provides documentation and resources to assist in understanding and effectively using the Umbraco CMS. It typically includes the following in the Getting Started Dashboard:

• Documentation: Comprehensive guides, tutorials, and references covering different aspects of Umbraco.

• Community Forums: Access to forums where you can ask questions, share knowledge, and seek assistance from other Umbraco community members.

• Resources: Stay updated with the latest news, access documentation, watch free video tutorials, and register for live demos.

• Training: Learn how to effectively use Umbraco through structured courses, webinars, and hands-on tutorials designed to enhance your proficiency with the CMS.

The Help section serves as a valuable resource hub in navigating and leveraging the capabilities of the Umbraco CMS effectively.

Custom Sections

Along with the default sections that come with Umbraco, you can create your own Custom Sections.

Access based on User Group

A User can access a particular section based on the User Group permissions.

Learn more about how to configure the permissions in the article about backoffice users.

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, specify the property editor for the Data Type to use by selecting from the "Property editor" list (as shown below).

Built-in Property Editors in Umbraco

Umbraco comes pre-installed with many useful property editors.

More information

• Customizing Data Types

Tutorials

• How to create a custom Property Editor

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

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

With Modelsbuilder

Add value programmatically

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.

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.

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

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

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

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:

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

In this article you can learn more about the common terms and concepts that are used throughout the Umbraco backoffice.

When you go to the backoffice for the first time, you're presented with the login screen.

A section in Umbraco is where you do specific tasks related to that section. For example Content, Settings and Users. You can navigate between the different sections of the backoffice by clicking the corresponding icon in the section menu.

The Section menu is the horizontal menu located on the top of the backoffice.

A tree is a hierarchical list of items related (and usually restricted) to a specific concept, like for example content or media.

Node

A node is an item in a tree. Media section items appear as nodes in the Media tree, while pages and content are displayed in the Content tree, and so on.

A dashboard is the main view you are presented with when entering a section within the backoffice. It can be used to show valuable information to the users of the system.

Editor

An editor is what you use to edit different items within the backoffice. There are editors specific to editing stylesheets, there are editors for editing Partial Views, and so forth.

Content is what you find in the Content section. Each item in the tree is called a content node. Each content node in the content tree consists of different fields, and each of them is defined by a Document Type.

Document Type

Document Types define the types of content nodes that backoffice users can create in the content tree. Each Document Type contains different properties. Each property has a specific Data Type for example text or number.

Properties

Every Document Type has properties. These are the fields that the content editor is allowed to edit for the content node.

Each Document Type property has a Data Type that defines the type of input of that property. Data Types reference a Property Editor and are configured in the Umbraco backoffice in the Settings section. A Data Type can be something basic (text string, number, true/false) or more complex (multi-node tree picker, image cropper, etc).

A property editor is a view used by Data Types to insert content into Umbraco. An example of a property editor is the Textarea. It's possible to have many Textarea Data Types with different settings that all use the Textarea property editor.

Media items are used to store assets like images and video within the Media section and can be referenced from your content.

Media Types

Media Types are similar to Document Types in Umbraco, except they are specifically for media items in the Media section.

Umbraco includes the following default Media Types - Article, Audio, File, Folder, Image, Vector Graphics (SVG), and Video.

A member is someone who has access to signup, register, and login into your public website and is not to be confused with Users.

Member Types

Similar to a Document Type and a Media Type. You are able to define custom properties to store on a member such as Twitter username or website URL.

A Template is where you define the HTML markup of your website and also where you output the data from your content nodes.

Packages

Users

A user is someone who has access to the Umbraco backoffice and is not to be confused with Members. When Umbraco has been installed a user will automatically be generated with the login (email) and password entered during installation. Users can be created, edited, and managed in the User section.

Document Blueprint provide a blueprint for content nodes based on an existing node.

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

@Model.MyMarkdownEditor

Without Modelsbuilder

@Model.Value("MyMarkdownEditor")

Add values programmatically

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

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

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

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

    // Create markdown value
    var markdownValue = new HtmlString("#heading  \n**strong text**");
    
    // Set the value of the property with alias 'myMarkdownEditor'. 
    content.SetValue("myMarkdownEditor", markdownValue);

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

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

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

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

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

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

Read about the Image Cropper here

Content Example

MVC View Example

Multiple enabled without Modelsbuilder

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

Multiple enabled with Modelsbuilder

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

Multiple disabled without Modelsbuilder

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

Multiple disabled with Modelsbuilder

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

Using crops

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

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

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

Explicitly retrieving global crops

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

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

Add values programmatically

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Returns: IEnumerable<Link> or Link

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

Data Type Definition Example

Content Example

MVC View Example - value converters enabled

Typed

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

If Max number of items is configured to 1

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

Add values programmatically

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

@using Umbraco.Cms.Core;
@using Umbraco.Cms.Core.Serialization
@using Umbraco.Cms.Core.Services;
@using Umbraco.Cms.Core.Models;
@inject IContentService 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

    // 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 externalLinks = 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 = Serializer.Serialize(externalLinks);


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

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

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

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

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

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

Alias: Umbraco.MemberPicker

Returns: IPublishedContent

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

Data Type Definition Example

Content Example

MVC View Example

Without Modelsbuilder

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

With Modelsbuilder

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

Add values programmatically

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

@using Umbraco.Cms.Core.Services;

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

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

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

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

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

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

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

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

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

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

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

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

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

With ModelsBuilder

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

Add values programmatically

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

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

 // Create a variable for the GUID of the page you want to update
 var guid = 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); 
}

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

@{
    @inject IPublishedSnapshotAccessor _publishedSnapshotAccessor

    // Set the value of the property with alias 'pageLabel'
     content.SetValue(Home.GetModelPropertyType(_publishedSnapshotAccessor, x => x.MyLabel).Alias, "A Preset 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

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

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

}