Before reading this document we highly recommend that you familiarise yourself with the basics of developing a custom Property Editor for Umbraco.

Setup your Property Editor as a Block Property Editor

In order for your editor to become a Block Editor you must setup your property editor through C#. The constructor of the class can be auto generated by your Integrated Development Environment (IDE).

using Umbraco.Cms.Core;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.WebAssets;
using Umbraco.Cms.Infrastructure.WebAssets;

namespace MyNamespace
{
    [DataEditor(
        "MyOwn.UnicornBlocksEditor",
        "Unicorn Blocks",
        "unicornblocks",
        ValueType = ValueTypes.Json,
        Group = Constants.PropertyEditors.Groups.Lists,
        Icon = "icon-thumbnail-list")]
    [PropertyEditorAsset(AssetType.Javascript, "/App_Plugins/UnicornBlocks/UnicornBlocks.controller.js")]
    public class UnicornBlocksPropertyEditor : BlockEditorPropertyEditor
    {
        public UnicornBlocksPropertyEditor(IDataValueEditorFactory dataValueEditorFactory, PropertyEditorCollection propertyEditors)
            : base(dataValueEditorFactory, propertyEditors)
        {
        }
    }

}

using System;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Strings;
using Umbraco.Cms.Core.WebAssets;
using Umbraco.Cms.Infrastructure.WebAssets;

namespace MyNamespace
{
    [DataEditor(
        "MyOwn.UnicornBlocksEditor",
        "Unicorn Blocks",
        "unicornblocks",
        ValueType = ValueTypes.Json,
        Group = Constants.PropertyEditors.Groups.Lists,
        Icon = "icon-thumbnail-list")]
    [PropertyEditorAsset(AssetType.Javascript, "/App_Plugins/UnicornBlocks/UnicornBlocks.controller.js")]
    public class UnicornBlocksPropertyEditor : BlockEditorPropertyEditor
    {
        public UnicornBlocksPropertyEditor(
            ILoggerFactory loggerFactory,
            Lazy<PropertyEditorCollection> propertyEditors,
            IDataTypeService dataTypeService,
            IContentTypeService contentTypeService,
            ILocalizedTextService localizedTextService,
            ILocalizationService localizationService,
            IShortStringHelper shortStringHelper,
            IJsonSerializer jsonSerializer)
            : base(loggerFactory,
                propertyEditors,
                dataTypeService,
                contentTypeService,
                localizedTextService,
                localizationService,
                shortStringHelper,
                jsonSerializer)
        {
        }
    }

}

Notice how the PropertyEditorAsset attribute is used to load the UnicornBlocks.controller.js JavaScript file.

Your Property Editor will need a PropertyValueConverter. Read more about Property Value Converters.

Data structure of Block Editors

The Block Editor data structure consists of three main parts:

Layout: The Layout defines Blocks that each will reference (by UDI) a content item in the list of data. The Layout object pairs keys with Property Editor aliases and their value type varies based on setup.

ContentData: A list of content items based on ElementTypes (IPublishedElement).

SettingsData: A list of content items based on ElementTypes (IPublishedElement).

In the following example the layout object "MyOwn.UnicornBlocksEditor" is of type Array.

{
  "layout": {
    "MyOwn.UnicornBlocksEditor": [
      {
        "contentUdi": "umb://element/fffba547615b4e9ab4ab2a7674845bc9"
      },
      {
        "contentUdi": "umb://element/e7dba547615b4e9ab4ab2a7674845bc9",
        "settingsUdi": "umb://element/a47667bcba54845b15b4e9ab4ab2a7c8"
      }
    ]
  },
  "contentData": [
    {
      "udi": "umb://element/fffba547615b4e9ab4ab2a7674845bc9",
      "contentTypeKey": "09876595489865786897",
      "__yourPropertyAlias__": "Hello world"
    },
    {
      "udi": "umb://element/e7dba547615b4e9ab4ab2a7674845bc9",
      "contentTypeKey": "123456789097654323456",
      "__yourPropertyAlias1__": "Hello world",
      "__yourPropertyAlias2__": "Hello world",
      "__yourPropertyAlias3__": "Hello world"
    }
  ],
  "settingsData": [
    {
      "udi": "umb://element/a47667bcba54845b15b4e9ab4ab2a7c8",
      "contentTypeKey": "09876595489865786897",
      "__yourPropertyAlias__": "Hello world"
    }
  ]
}

Client side code

Basic knowledge for understanding how to work with Block Editor data

We created the BlockEditorModelObject to aid in managing the presented Data Structure in the Block Editor.

To get a better understanding of what the Model Object does for you, we need to look at some usages of the Model Object.

Maintain and work with the Layout of a Block Editor

The layout of a Block Editor can be any structure. Therefore the Model Object (BlockEditorModelObject) cannot maintain this data. Our usage of the Model Object becomes complex. We give it a reference to a layout entry and perform an action that may need to reflect changes back to the layout.

Since the origin of blocks is in the layout the Model Object only can serve as a helper to maintain and create data. Therefore the Property Editor code will be using the layout as origin, using the Model Object to help manage specific parts.

This is explained in more detail below.

The basic setup for a Block Editor

Instantiate a Model Object and load dependencies. Provide the basic structure for the layout property when receiving the reference to it:

// We must get a scope that exists in all the lifetime of this data. Across variants and split-view.
var scopeOfExistence = $scope;
// Setup your component to require umbVariantContentEditors and vm.umbElementEditorContent. If one of them is avaiable use the method getScope to retrieve a shared scope for multiple editors of this content.
if(vm.umbVariantContentEditors && vm.umbVariantContentEditors.getScope) {
    scopeOfExistence = vm.umbVariantContentEditors.getScope();
} else if(vm.umbElementEditorContent && vm.umbElementEditorContent.getScope) {
    scopeOfExistence = vm.umbElementEditorContent.getScope();
}
// Define variables for layout and modelObject as you will be using these throughout your property editor.
vm.layout;
var modelObject;

// When we are ready we can instantiate the Model Object and load any dependencies.
vm.$onInit = function() {
  modelObject = blockEditorService.createModelObject(vm.model.value, vm.model.editor, vm.model.config.blocks, scopeOfExistence);
  modelObject.load().then(onLoaded);
}
function onLoaded() {
  // Define the default layout, this is used when there is no data stored for this property.
  var defaultLayout = [];
  // We store a reference to layout as we have to maintain this.
  // The getLayout method gives us a reference to the layout-object based on the property-editor alias. The defaultLayout will be initialized if it does not exist.
  vm.layout = modelObject.getLayout(defaultLayout);
}

Create a Block

Use the Model Object to create a Block and append the returned layout-entry to the layout.

In the following example we will create a new block and append it at the appropriate location in the 'layout' object:

// continuing from previous example.

// Creates a block and returns a layout entry. The layout entry is not part of layout yet as its not managed by the Model Object.
var layoutEntry = modelObject.create(contentTypeKey);
if (layoutEntry === null) {
  // The creation was not successful, therefore exit and without appending anything to our 'layout' object.
  return false;
}
// If we reach this line, we are good to add the layoutEntry to layout model.
// In this example our layout is an array and we would like to append the new block as the last entry.
vm.layout.push(layoutEntry);

Working with Blocks

The layout-entries alone do not provide much value when displaying or editing Blocks.

Our Model Object allows obtaining a Block Object by parsing a block's layout-entry for a specific Block.

The Block Object provides data of interest. The most important of these properties are: Block configuration, a label and the Block content in the Element Type Data Model format. This Content-model is useful for building the UI for editing the Content of a Block.

This example uses the Model Object to retrive a Block Object for outputting its label in the console.

// continuing from the basic setup example.

if (vm.layout.length > 0) {
  // Get first entry of from the layout, which is an array in this example.
  var firstLayoutEntry = vm.layout[0];

  // Create a Block Object for that entry.
  var block = modelObject.getBlockObject(firstLayoutEntry);

  // Check if the Block Object creation went well. (If a block is supported by the configuration of the Property Editor)
  if (block !== null) {
    console.log(block.label);
  }
}

This similar example uses the Block Object for setting a value on the first property in the Blocks Content.

// continuing from the basic setup example.

if (vm.layout.length > 0) {
  // Get first entry of from the layout, which is an array in this example.
  var firstLayoutEntry = vm.layout[0];

  // Create a Block Object for that entry.
  var block = modelObject.getBlockObject(firstLayoutEntry);

  // Check if the Block Object creation went well. (If a block is supported by the configuration of the Property Editor)
  if (block !== null) {

    // This line edits the value of 'myProp' directly, available by 'block.data':
    block.data.myProp = "Hello world";

    // Alternatively you can use this line, which edits the data throught the Element Type data model avaiable in 'block.content':
    block.content.variants[0].tabs[0].properties[0].value = "Hello world"; // This value will automatically be synced to the Property Editors Data Model, ´block.data.myProp´
  }
}

See blockEditorModelObject for the getBlockObject method for more information on the properties avaiable on a Block Object.

Remove a Block

Removing a Block and destroying its data is done by calling the removeDataAndDestroyModel method of the Model Object, which allows us to maintain the 'layout' object.

Your code will be based on working with Block Objects and therefore removal of a Block is be done by referring to a Block Object.

This example shows how to remove the first Block of our imaginary Block Editor and remove the block from our layout.

// continuing from the basic setup example.

if (vm.layout.length > 0) {
  // Get first entry of from the layout, which is an array in this sample.
  var firstLayoutEntry = vm.layout[0];

  // Create a Block Object for that entry.
  var block = modelObject.getBlockObject(firstLayoutEntry);

  // Check if the Block Object creation went well. (If a block isnt supported by the configuration of the Property Editor)
  if(block !== null) {

    modelObject.removeDataAndDestroyModel(block);// Removing the data of our block and destroying the Block Object for performance reasons.

    // We need to maintain the 'layout' object, so therefor its up to our code to remove the block from the 'layout' object.
    const index = array.indexOf(5);
    if (index > -1) {
      vm.layout.splice(index, 1);
    }
  }
}

Manage Block Objects for general use through out your Property Editor

Block Objects are used extensively and should be available throughout your Block Editor's runtime, rather than created for each action.

You probably want to use BlockObjects for your property-editor view. We append them to layout entries, so you can access them as properties from the layout object.

// continuing from the basic setup example.

var invalidLayoutItems = [];

// Append the blockObjects to our layout.
vm.layout.forEach(entry => {

// As we might have the same property-editor displayed multiple times on screen (splitview) we only need to initialize a BlockObject if its not already in place.

    // $block must have the 'data' property to be a valid BlockObject, if not it is considered a destroyed blockObject.
    if (entry.$block === undefined || entry.$block === null || entry.$block.data === undefined) {
        var block = modelObject.getBlockObject(entry);

        // If this entry was not supported by our property-editor it would return 'null'.
        if (block !== null) {
            entry.$block = block;
        } else {
          // We didnt succeed initializing this Block, therefore we need to filter this out of 'layout'. This only happens if the content data of the block couldn't be found.
            invalidLayoutItems.push(entry);
        }
    }
});

// remove the ones that are invalid
invalidLayoutItems.forEach(entry => {
    var index = vm.layout.findIndex(x => x === entry);
    if (index >= 0) {
        vm.layout.splice(index, 1);
    }
});

The following example loops through a layout array to display the contentUdi of each block:

<div ng-repeat="layoutEntry in vm.layout track by layoutEntry.$block.key">

    <h3 ng-bind="layout.$block.data.udi"></h3>

</div>

The package.manifest JSON file format is used to describe one or more custom Umbraco property editors, grid editors or parameter editors. This page outlines the file format and properties found in the JSON.

Sample Manifest

This is a sample manifest, it is always stored in a folder in /App_Plugins/{YourPackageName}, with the name package.manifest

{
    "name": "Suggestions",
    "version": "1.0.0 beta",
    "allowPackageTelemetry": true,
    "bundleOptions": "Default",
    "packageView": "/App_Plugins/Suggestions/suggestion-config.html",
    "propertyEditors": [
        {
            "alias": "Suggestions",
            "name": "Suggestions",
            "editor": {
                "view": "/App_Plugins/Suggestions/suggestion.html",
                "hideLabel": true,
                "valueType": "JSON",
                "supportsReadOnly": true
            }
        }
    ],
    "javascript": [
        "/App_Plugins/Suggestions/suggestion.controller.js"
    ]
}

Sample Manifest with Csharp

You can also register your files by implementing a IManifestFilter instead of creating a package.manifest. Create a ManifestFilter.cs file and implement the IManifestFilter interface. Then define the composer using the IComposer interface.

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Manifest;
using Umbraco.Cms.Core.PropertyEditors;

namespace MyProject
{
	public class ManifestComposer : IComposer
	{
		//composer
		public void Compose(IUmbracoBuilder builder)
		{
			builder.ManifestFilters().Append<ManifestFilter>();
		}
	}
	public class ManifestFilter : IManifestFilter
	{
		private readonly IDataValueEditorFactory _dataValueEditorFactory;

		public ManifestFilter(IDataValueEditorFactory dataValueEditorFactory)
		{
			_dataValueEditorFactory = dataValueEditorFactory;
		}

		public void Filter(List<PackageManifest> manifests)
		{
			manifests.Add(new PackageManifest
			{
				PackageName = "Suggestions",
				Scripts = new[]
				{
					"/App_Plugins/Suggestions/suggestion.controller.js"
				},				
				Version = "1.0.0"
			});
		}
	}
}

Root elements

The manifest can contain seven root collections, none of them are mandatory:

{
    "propertyEditors": [],
    "gridEditors": [],
    "parameterEditors": [],
    "dashboards": [],
    "sections": [],
    "contentApps": [],
    "javascript": [],
    "css": []
}

Telemetry elements

From version 9.2, some additional root elements were added. Their purpose is to control and facilitate telemetry for the package but none of these are mandatory. The properties are:

• name - Allows you to specify a friendly name for your package that will be used for telemetry, if no name is specified the name of the folder will be used instead

• version - The version of your package, if this is not specified there will be no version specific information for your package

• allowPackageTelemetry - Allows you to entirely disable telemetry for your package if set to false, defaults to true.

Example package.manifest

{
    "name": "My Awesome Package",
    "version": "1.0.0",
    "allowPackageTelemetry": true
}

Property Editors

propertyEditors returns an array of property editor definitions, each object specifies an editor to make available to data types as an editor component. These editors are primarily property editors for content, media and members. They can also be made available as a macro parameter editor.

The basic values on any editor are alias, name and editor. These three must be set. Furthermore the editor value is an object with additional configuration options, it must contain a view value.

{
    "alias": "my.editor.alias",
    "name": "My friendly editor name",
    "editor": {
        "view": "/App_Plugins/MyEditorName/view.html"
    },
    "prevalues": {
        "fields": []
    }
}

• alias The alias of the editor, this must be unique, its recommended to prefix with your own "namespace".

• name The name visible to the user in the UI, should also be unique.

• editor Object containing editor configuration (see below).

• isParameterEditor enables the property editor as a macro parameter editor can be true/false.

• prevalues Configuration of editor prevalues (see below).

• defaultConfig Default configuration values (see below).

• icon A CSS class for the icon to be used in the 'Select Editor' dialog: e.g. icon-autofill.

• group The group to place this editor in within the 'Select Editor' dialog. Use a new group name or alternatively use an existing one such as Pickers.

• defaultConfig Provides a collection of default configuration values, in case the property editor is not configured or is using a parameter editor, which doesn't allow configuration. The object is a key/value collection and must match the prevalues fields keys.

Editor

editor Besides setting a view, the editor can also contain additional information.

"editor": {
    "view": "/App_Plugins/MyEditorName/view.html",
    "hideLabel": true,
    "valueType": "TEXT",
    "validation": {},
    "supportsReadOnly": true,
    "isReadOnly": false
}

• view Path to the HTML file to use for rendering the editor.

• hideLabel Turn the label on or off by using true or false, respectively.

• valueType Sets the database type the value is stored as, by default it's string.

• validation Object describing required validators on the editor.

• supportsReadOnly Sets whether the editor supports read-only mode, if set to true, the editor is expected to have its own implementation of the read-only mode.

• isReadOnly Disables editing the value.

valueType sets the kind of data the editor will save in the database, its default setting is string. The available options are:

• STRING Stores the value as an nvarchar in the database

• DATETIME Stores the value as datetime in the database

• TEXT Stores the value as ntext in the database

• INT Stores the value as a bigint in the database

• JSON Stored as ntext and automatically serialized to a dynamic object

Pre Values

preValues is a collection of prevalue editors, used for configuring the property editor, the prevalues object must return an array of editors, called fields.

"prevalues": {
    "fields": [
        {
            "label": "Enable something",
            "description": "This is a description",
            "key": "enableStuff",
            "view": "boolean"
        }
    ]
}

Each field contains a number of configuration values:

• label The label shown on the Data Type configuration screen

• description Help text displayed underneath the label

• key The key the prevalue is stored under (see below)

• view Path to the editor used to configure this prevalue (see below)

key on a prevalue, determines where it's stored in the database. If you give your prevalue the key "wolf" then this key will be used in the prevalue table.

It also means when this property editor is used on a property, the prevalue will be exposed on the model's configuration object. This occurs inside the property editor's controller, as shown below:

// this is the property value
$scope.model.value = "hello";

// this is the configuration on the property editor
$scope.model.config

// this is our specific prevalue with the alias wolf
$scope.model.config.wolf

view config value points the prevalue editor to an editor to use. This follows the same concept as any other editor in Umbraco, but with prevalue editors there are a couple of conventions.

If you specify a name like boolean then Umbraco will look at /wwwroot/umbraco/views/prevalueeditors/boolean/boolean.html for the editor view. If you wish to use your own, you specify the path like /App_Plugins/{YourPackageName}/prevalue-editor.html.

Default Config

The defaultConfig object provides a collection of default configuration values in case the property editor is not configured or is using a parameter editor. This object is a key/value collection and must match the prevalue field keys.

"defaultConfig": {
    "wolf": "nope",
    "editor": "hello",
    "random": 1234
}

Grid Editors

Similar to how the propertyEditors array defines one or more property editors, gridEditors can be used to define editors specific to the grid. Setting up the default richtext editor in the Umbraco grid could look like:

{
  "gridEditors": [
    {
      "name": "Rich text editor",
      "alias": "rte",
      "view": "rte",
      "icon": "icon-article"
    }
  ]
}

However the default grid editors are already configured. You can see the Grid Editors page for more information on grid editors.

Parameter Editors

parameterEditors returns an array of editor objects, each object specifies an editor to make available to macro parameters as an editor component. These editors work solely as parameter editors and will not show up on the property editors list.

The parameter editors array follows the same format as the property editors described above. However, it cannot contain prevalues since there are no configuration options for macro parameter editors.

JavaScript

javascript returns a string[] of JavaScript files to load on application start

{
  "javascript": [
    "/App_Plugins/MyEditorName/MyEditorName.controller.js",
    "/App_Plugins/MyEditorName/MyEditorName.js"
  ]
}

CSS

css returns a string[] of css files to load on application start

{
  "css": [
    "/App_Plugins/MyEditorName/MyEditorName.css",
    "/App_Plugins/MyEditorName/hibba.css"
  ]
}

Bundling

bundleOptions is an enumerable type that expects one of the following values:

• Default - The default bundling behavior for assets in the package folder where the assets will be bundled with the typical packages bundle.

• None - The assets in the package will not be processed at all and will all be requested as individual assets and will effectively be a bundle that has composite processing turned off for both debug and production.

• Independent - The packages assets will be processed as its own separate bundle. (In debug, files will not be processed)

JSON Schema

The package.manifest JSON file has a hosted online JSON schema file. This allows editors such as Visual Studio, Rider, and Visual Studio Code to have autocomplete/intellisense support when creating and editing package.manifest files. This helps to avoid mistakes or errors when creating your package.manifest files.

Setting up Visual Studio 2015+

To associate the hosted JSON schema file to all package.manifest files you will need to perform the following inside of Visual Studio 2015.

• Tools -> Options

• Browse down to Text Editor -> File Extension

• Add manifest into the Extension box

• Select JSON Editor from the dropdown and add the mapping

• Open a package.manifest file and ensure in the top left hand corner you see the schema with the URL set to http://json.schemastore.org/package.manifest. You can also add the schema inline in the json file (see below).

Setting up JetBrains Rider 2019+

To associate the hosted JSON schema file to all package.manifest files you will need to perform the following inside of Visual Studio 2015.

• File -> Settings

• Browse down to Editor -> File Types -> JSON

• Add package.manifest to the list of file pattern names.

• Browse down to Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings

• Add new by clicking the + symbol

• Add package.manifest as Name

• Add https://json.schemastore.org/package.manifest as the Schema File or URL, or choose package.manifest from the Remote Schema URls

• Add package.manifest as File path pattern

• Open a package.manifest file and ensure in the bottom tool bar you see the schema is detected as package.manifest.

Setting up Visual Studio Code

To associate the hosted JSON schema file to all package.manifest files you will need to perform the following inside of Visual Studio Code editor.

• File -> Preferences -> Settings. The Settings window opens.

• In the User tab, go to Extensions -> JSON -> Schemas.
• Select Edit in settings.json from the Schemas section.

• Add the following snippet in the settings.json file:

  Copy

  {
      "json.schemas": [
          {
              "fileMatch": [
                  "manifest.json"
              ],
              "url": "http://json.schemastore.org/package.manifest"
          }
      ]
  }

Adding inline schema

Editors like Visual Studio can use the $schema notation in your file.

{
    "$schema" : "http://json.schemastore.org/package.manifest",
    "javascript": [],
    "other properties": ""
}

A Property Value Converter converts a property editor's database-stored value to another type. The converted value can be accessed from MVC Razor or any other Published Content API.

For example the standard Umbraco Core "Content Picker" stores a nodeId as String type. However if you implement a converter it could return an IPublishedContent object.

Published property values have four "Values":

• Source - The raw data stored in the database, this is generally a String

• Intermediate - An object of a type that is appropriate to the property, for example a nodeId should be an Int or a collection of nodeIds would be an integer array, Int[]

• Object - The object to be used when accessing the property using a Published Content API, for example UmbracoHelper's GetPropertyValue<T> method

• XPath - The object to be used when the property is accessed by XPath; This should generally be a String or an XPathNodeIterator

Registering PropertyValueConverters

PropertyValueConverters are automatically registered when implementing the interface. Any given PropertyEditor can only utilize a single PropertyValueConverter.

If you are implementing a PropertyValueConverter for a PropertyEditor that doesn't already have one, creating the PropertyValueConverter will automatically enable it. No further actions are needed.

If you aim to override an existing PropertyValueConverter, possibly from Umbraco or a package, additional steps are necessary. Deregister the existing one to prevent conflicts in this scenario.

using System.Linq;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        //If the type is accessible (not internal) you can deregister it by the type:
        builder.PropertyValueConverters().Remove<MyCustom.StandardValueConnector>();

        //If the type is not accessible you will need to locate the instance and then remove it:
        var contentPickerValueConverter = builder.PropertyValueConverters().GetTypes().FirstOrDefault(x => x.Name == "ContentPickerValueConverter");
        if (contentPickerValueConverter != null)
        {
            builder.PropertyValueConverters().Remove(contentPickerValueConverter);
        }
    }
}

The built-in PropertyValueConverters included with Umbraco, are currently marked as internal. This means you will not be able to remove them by type since the type isn't accessible outside of the namespace. In order to remove such PropertyValueConverters, you will need to look up the instance by name and then deregister it by the instance. This could be the case for other PropertyValueConverters included by packages as well, depending on the implementation details.

Implementing the Interface

Implement IPropertyValueConverter from the Umbraco.Cms.Core.PropertyEditors namespace on your class

public class ContentPickerValueConverter : IPropertyValueConverter

Methods - Information

IsConverter(IPublishedPropertyType propertyType)

This method is called for each PublishedPropertyType (Document Type Property) at application startup. By returning True your value converter will be registered for that property type and your conversion methods will be executed whenever that value is requested.

Example: Checking if the IPublishedPropertyType EditorAlias property is equal to the alias of the core content editor. This check is a string comparison but we recommend creating a constant for it to avoid spelling errors:

public bool IsConverter(IPublishedPropertyType propertyType)
{
    return propertyType.EditorAlias.Equals(Constants.PropertyEditors.Aliases.ContentPicker);
}

IsValue(object value, PropertyValueLevel level)

This method is called to determine if the passed-in value is a value, and is of the level specified. There's a basic implementation of this in PropertyValueConverterBase.

GetPropertyValueType(IPublishedPropertyType propertyType)

This is where you can specify the type returned by this Converter. This type will be used by ModelsBuilder to return data from properties using this Converter in the proper type.

Example: Content Picker data is being converted to IPublishedContent.

public Type GetPropertyValueType(IPublishedPropertyType propertyType)
{
    return typeof(IPublishedContent);
}

PropertyCacheLevel GetPropertyCacheLevel(IPublishedPropertyType propertyType)

Here you specify which level the property value is cached at.

A property value can be cached at the following levels:

PropertyCacheLevel.Unknown

Do not use this cache level unless you know exactly what you're doing. We recommend using the PropertyCacheLevel.Element level.

PropertyCacheLevel.Element

The property value will be cached until its element is modified. The element is what holds (or owns) the property. For example:

• For properties used at the page level, the element is the entire page.

• For properties contained within Block List items, the element is the individual Block List item.

This is the most commonly used cache level and should be your default, unless you have specific reasons to do otherwise.

PropertyCacheLevel.Elements

The property value will be cached until any element (see above) is changed. This means that any change to any page will clear the property value cache.

This is particularly useful for property values that contain references to other content or elements. For example, this cache level is utilized by the Content Picker to clear its property values from the cache upon content updates.

PropertyCacheLevel.Snapshot

The property value will only be cached for the duration of the current snapshot.

A snapshot represents a point in time. For example, a snapshot is created for every content request from the frontend. When accessing a property in a snapshot using this cache level, it gets converted, cached throughout the snapshot, and later cleared.

For all intents and purposes, think of this cache level as "per request". If your property value should only be cached per request, this is the cache level you should use. Use it with caution, as the added property conversions incur a performance penalty.

PropertyCacheLevel.None

The property value will never be cached. Every time a property value is accessed (even within the same snapshot) property conversion is performed explicitly.

Use this cache level with extreme caution, as it incurs a massive performance penalty.

public PropertyCacheLevel GetPropertyCacheLevel(IPublishedPropertyType propertyType)
{
    return PropertyCacheLevel.Elements;
}

Methods - Conversion

There are a few different levels of conversion which can occur.

ConvertSourceToIntermediate(IPublishedElement owner, IPublishedPropertyType propertyType, object source, bool preview)

This method should convert the raw data value into an appropriate type. For example, a node identifier stored as a String should be converted to an Int or Udi.

Include a using Umbraco.Extensions; to be able to use the TryConvertTo extension method.

public object ConvertSourceToIntermediate(IPublishedElement owner, IPublishedPropertyType propertyType, object source, bool preview)
{
    if (source == null) return null;

    var attemptConvertInt = source.TryConvertTo<int>();
    if (attemptConvertInt.Success)
        return attemptConvertInt.Result;

    var attemptConvertUdi = source.TryConvertTo<Udi>();
    if (attemptConvertUdi.Success)
        return attemptConvertUdi.Result;

    return null;
}

ConvertIntermediateToObject(IPublishedElement owner, IPublishedPropertyType propertyType, PropertyCacheLevel referenceCacheLevel, object inter, bool preview)

This method converts the Intermediate to an Object. The returned value is used by the GetPropertyValue<T> method of IPublishedContent.

The below example converts the nodeId (converted to Int or Udi by ConvertSourceToIntermediate) into an 'IPublishedContent' object.

public object ConvertIntermediateToObject(IPublishedElement owner, IPublishedPropertyType propertyType, PropertyCacheLevel referenceCacheLevel, object inter, bool preview)
{
    if (inter == null)
        return null;

    if ((propertyType.Alias != null && PropertiesToExclude.Contains(propertyType.Alias.ToLower(CultureInfo.InvariantCulture))) == false)
    {
        IPublishedContent content;
        if (inter is int id)
        {
            content = _publishedSnapshotAccessor.PublishedSnapshot.Content.GetById(id);
            if (content != null)
                return content;
        }
        else
        {
            var udi = inter as GuidUdi;
            if (udi == null)
                return null;
            content = _publishedSnapshotAccessor.PublishedSnapshot.Content.GetById(udi.Guid);
            if (content != null && content.ContentType.ItemType == PublishedItemType.Content)
                return content;
        }
    }

    return inter;
}

ConvertIntermediateToXPath(IPublishedElement owner, IPublishedPropertyType propertyType, PropertyCacheLevel referenceCacheLevel, object inter, bool preview)

This method converts the Intermediate to XPath. The return value should generally be of type String or XPathNodeIterator.

In the example below, we convert the nodeId (converted by ConvertSourceToIntermediate) back into a String.

public object ConvertIntermediateToXPath(IPublishedElement owner, IPublishedPropertyType propertyType, PropertyCacheLevel referenceCacheLevel, object inter, bool preview)
{
    if (inter == null) return null;
    return inter.ToString();
}

Sample

Content Picker to IPublishedContent using IPropertyValueConverter interface

This section describes how to work with and create Property Editors. A property editor is the editor used to insert content into Umbraco. See here for definition

Tutorials - Creating a property editor

• Creating a property editor

• Adding configuration to a property editor

• Integrating services with a property editor

• Adding server side data to a property editor

Package Manifest

Reference for the package.manifest JSON file format to register one or more property editors for Umbraco.

Property Value Converters

Convert the stored property data value to a useful object returned by the Published Content APIs.

Property Actions

Use Property Actions to add additional functionaility to your custom property editors.

Build a Block Editor

Learn how to build your own Block Editors.

Tracking References

Learn how to extend Property editors to track entity references inside the property editor.

More information

• Built in Property Editors

Property Actions are a built-in feature that provide a generic place for secondary functionality for property editors.

Property Actions appear as a small button next to the label of the property, which expands to show the available actions. They are defined and implemented in the Property Editor, making it open as to what a Property Action is.

Data Structure of Property Actions

Property Editors are an array of objects defining each action. An action is defined by the following properties:

{
    labelKey: 'clipboard_labelForRemoveAllEntries',
    labelTokens: [],
    icon: 'trash',
    method: removeAllEntries,
    isDisabled: true
}

We use labelKey and labelTokens to retrieve a localized string that is displayed as the Actions label. See localization for more info.

isDisabled is used to disable an Action, which change the visual appearance and prevents interaction. Use this option when an action wouldn't provide any change. In the example above, the action remove all entries would not have any impact if there is no entries.

Implementation

The implementation of Property Actions varies depending on whether your Property Editor is implemented with a Controller or as a Component.

Controller Implementation

When your Property Editor is implemented with a Controller, use the following approach for the Property Action:

angular.module("umbraco").controller("My.MarkdownEditorController", function ($scope) {

function myActionExecutionMethod() {
    alert('My Custom Property Action Clicked');
    // Disable the action so it can not be re-run
    // You may have custom logic to enable or disable the action
    // Based on number of items selected etc...
    myAction.isDisabled = true;
};

var myAction = {
    labelKey: 'general_labelForMyAction',
    labelTokens: [],
    icon: 'action',
    method: myActionExecutionMethod,
    isDisabled: false
}

var propertyActions = [
    myAction
];

this.$onInit = function () {
    if ($scope.umbProperty) {
        $scope.umbProperty.setPropertyActions(propertyActions);
    }
};


});

Component Implementation

Follow this guide if your Property Editor is implemented as a Component. The Component must be configured to retrieve an optional reference to umbProperty. The requirement must be optional because property-editors are implemented in scenarios where it's not presented.

See the following example:

angular.module('umbraco').component('myPropertyEditor', {
    controller: MyController,
    controllerAs: 'vm',
    require: {
        umbProperty: '?^umbProperty'
    }
    …
});

See the following example for implementation of Property Actions in a Component, notice the difference is that we are parsing actions to this.umbProperty.setPropertyActions(...).

var myAction = {
    labelKey: 'general_labelForMyAction',
    labelTokens: [],
    icon: 'action',
    method: myActionExecutionMethod,
    isDisabled: false
}

var propertyActions = [
    myAction
];

this.$onInit = function () {
    if (this.umbProperty) {
        this.umbProperty.setPropertyActions(propertyActions);
    }
};

Generally Umbraco supports two different ways to declare a property editor. Most commonly one would create a package.manifest file, and then use it for declaring one or more property editors. But as an alternative, property editors can also be declared using C#.

A property editor consists of a number of mandatory properties, and some optional ones as well. As such, the outer JSON object for the property editor has the following properties:

The editor object then has the following properties:

Using a Package Manifest

A package manifest is a file specific to your package or custom code. This file is always stored in a folder in /App_Plugins/{YourPackageName}, and with the name package.manifest :

{
    "propertyEditors": [
        {
            "alias": "Sir.Trevor",
            "name": "Sir Trevor",
            "editor": {
                "view": "/App_Plugins/SirTrevor/SirTrevor.html",
                "hideLabel": true,
                "valueType": "JSON"
            }
        }
    ],
    "javascript": [
        "/App_Plugins/SirTrevor/SirTrevor.controller.js"
    ]
}

This example manifest specifies a Sir Trevor property editor via the propertyEditors collection, and also adds a single JavaScript file via the javascript property.

The actual Sir Trevor property editor has some additional configuration. It's a block based editor, so for instance it has a prevalue for setting the maximum amount of blocks allowed. In full, the package.manifest file for the Sir Trevor package looks like:

{
  "propertyEditors": [
    {
      "alias": "Sir.Trevor",
      "name": "Sir Trevor",
      "editor": {
        "view": "/App_Plugins/SirTrevor/SirTrevor.html",
        "hideLabel": true,
        "valueType": "JSON"
      },
      "prevalues": {
        "fields": [
          {
            "label": "Maximum number of blocks",
            "description": "The total maximum number of blocks (of any type) that can be displayed (0 = infinite).",
            "key": "blockLimit",
            "view": "requiredfield",
            "validation": [
              {
                "type": "Required"
              }
            ]
          },
          {
            "label": "Align editor centered",
            "description": "If the editor doesn't span the entire width of the content editing area, center it. Otherwise left aligned.",
            "key": "editorAlignCentered",
            "view": "boolean"
          },
          {
            "label": "Editor width",
            "description": "The width the Sir Trevor editor will expand to, most likely 100%.",
            "key": "editorWidth",
            "view": "requiredfield",
            "validation": [
              {
                "type": "Required"
              }
            ]
          },
          {
            "label": "Maximum editor width",
            "description": "The maximum width the Sir Trevor editor will expand to, i.e. 500px or 80%.",
            "key": "editorMaxWidth",
            "view": "requiredfield",
            "validation": [
              {
                "type": "Required"
              }
            ]
          },
          {
            "label": "Block types",
            "description": "Configure the block types available to the user.",
            "key": "blocktypes",
            "view": "~/App_Plugins/SirTrevor/settings/blocktypes.html"
          }
        ]
      }
    }
  ],
  "javascript": [
    "/App_Plugins/SirTrevor/SirTrevor.controller.js",
    "/App_Plugins/SirTrevor/settings/settings.blocktypes.controller.min.js",
    "/App_Plugins/SirTrevor/settings/settings.resource.min.js"
  ]
}

Using Csharp

The same property editor can be declared using C# instead using the DataEditor class and decorating the class with the DataEditor attribute:

using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.WebAssets;
using Umbraco.Cms.Infrastructure.WebAssets;

namespace UmbracoEightExamples.PropertyEditors
{
    [DataEditor(
        "Sir.Trevor",
        EditorType.PropertyValue,
        "Sir Trevor",
        "/App_Plugins/SirTrevor/SirTrevor.html",
        ValueType = ValueTypes.Json,
        HideLabel = true)]
    [PropertyEditorAsset(AssetType.Javascript, "/App_Plugins/SirTrevor/SirTrevor.controller.js")]
    public class SirTrevorEditor : DataEditor
    {
        public SirTrevorEditor(
            IDataValueEditorFactory dataValueEditorFactory,
            EditorType type = EditorType.PropertyValue)
            : base(dataValueEditorFactory, type)
        {
        }
    }
}

Also notice how the PropertyEditorAsset attribute is used to load the SirTrevor.controller.js JavaScript file.

DataEditor attribute

The DataEditor attribute shown in the example above is the primary component to declaring the property editor in C#. Notice that the first four properties must be set through the constructor.

PropertyEditorAsset attribute

As shown in the C# example, the PropertyEditorAsset attribute was used to make Umbraco load the specified JavaScript file.

The constructor of the attribute takes the type of the assets as the first parameter. Possible values are either AssetType.Javascript or AssetType.Css. The second parameter is the URL of the asset.

DataEditor class

In the example above, the SirTrevorEditor class doesn't really do much. For more basic property editors, the C# approach may require a bit more work compared to that of package.manifest files. But as property editors grow in complexity, using C# becomes a bit more useful - and also lets you do things not possible with package.manifest files.

The DataEditor class defines a virtual CreateConfigurationEditor method. It returns a model which is used for the Angular view when editing the prevalues of a Data Type.

Virtual methods are methods declared in a parent class. These methods have a default implementation that can be overridden in classes that inherit from the parent class. For instance in the example below, we can override the method and provide our own SirTrevorConfigurationEditor instead of what Umbraco returns by default.

using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.WebAssets;
using Umbraco.Cms.Infrastructure.WebAssets;

namespace UmbracoEightExamples.PropertyEditors
{
    [DataEditor(
        "Sir.Trevor",
        EditorType.PropertyValue,
        "Sir Trevor",
        "/App_Plugins/SirTrevor/SirTrevor.html",
        ValueType = ValueTypes.Json,
        HideLabel = true)]
    [PropertyEditorAsset(AssetType.Javascript, "/App_Plugins/SirTrevor/SirTrevor.controller.js")]
    public class SirTrevorEditor : DataEditor
    {
        public SirTrevorEditor(
            IDataValueEditorFactory dataValueEditorFactory,
            EditorType type = EditorType.PropertyValue)
            : base(dataValueEditorFactory, type)
        {
        }

        protected override IConfigurationEditor CreateConfigurationEditor() => new SirTrevorConfigurationEditor();

    }
}

In this case, the SirTrevorConfigurationEditor class doesn't do much either - but notice that it inherits from ConfigurationEditor<SirTrevorConfiguration>, meaning the configuration will be of type SirTrevorConfiguration:

using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Services;

namespace UmbracoEightExamples.PropertyEditors
{
    public class SirTrevorConfigurationEditor : ConfigurationEditor<SirTrevorConfiguration>
    {
        public SirTrevorConfigurationEditor(IIOHelper ioHelper, IEditorConfigurationParser editorConfigurationParser) : base(ioHelper, editorConfigurationParser)
        {
        }
    }
}

The referenced SirTrevorConfiguration class is then what declares the configuration fields of when editing a Data Type using the Sir Trevor property editor:

using Umbraco.Cms.Core.PropertyEditors;

namespace UmbracoEightExamples.PropertyEditors
{
    public class SirTrevorConfiguration
    {
        [ConfigurationField("blockLimit", "Maximum number of blocks", "requiredfield",
            Description = "The total maximum number of blocks (of any type) that can be displayed (0 = infinite).")]
        public int BlockLimit { get; set; }

        [ConfigurationField("editorAlignCentered", "Align editor centered", "boolean",
            Description =
                "If the editor doesn't span the entire width of the content editing area, center it. Otherwise left aligned.")]
        public bool EditorAlignCentered { get; set; }

        [ConfigurationField("editorWidth", "Editor width", "requiredfield",
            Description = "The width the Sir Trevor editor will expand to, most likely 100%.")]
        public int EditorWidth { get; set; }

        [ConfigurationField("editorMaxWidth", "Maximum editor width", "requiredfield",
            Description = "The maximum width the Sir Trevor editor will expand to, i.e. 500px or 80%.")]
        public int EditorMaxWidth { get; set; }

        [ConfigurationField("blocktypes", "Block types", "/App_Plugins/SirTrevor/settings/blocktypes.html",
            Description = "Configure the block types available to the user.")]
        public object BlockTypes { get; set; }
    }
}

A benefit of this approach (opposed to package.manifest files) is that we can now refer to the configuration using a strongly typed model - eg. as in this example Razor view:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
@using Umbraco.Cms.Core.Services
@using UmbracoEightExamples.PropertyEditors
@inject IDataTypeService DataTypeService

@{
    var dt = DataTypeService.GetDataType(1234);

    if (dt is not null)
    {
        <pre>@dt.Name</pre>

        <pre>@(dt.Configuration as SirTrevorConfiguration)</pre>

        <pre>@(dt.ConfigurationAs<SirTrevorConfiguration>())</pre>
    }
}

Both instances of IDataType and PublishedDataType have a Configuration property. When looking across all data types and property editors, there is no common type for the configuration, so the return value is object. To get the strongly typed model, you can either cast the configuration value on your own, or use the generic ConfigurationAs extension method as shown above.

Like mentioned before, the SirTrevorConfigurationEditor class doesn't really do much in this example with the Sir Trevor property editor. But the Multi Node Tree Picker and others of Umbraco's build in property editors also override the ToValueEditor method.

This method is used when the strongly typed configuration value is converted to the model used by the Angular logic in the backoffice. So with the implementation of the MultiNodePickerConfigurationEditor class, some additional configuration fields are sent along. For instance that it's a multi picker and that the ID type should be URI's. These are configuration values that the user should not be able to edit, but the property editor may still rely on them.

using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.Services;

namespace Umbraco.Cms.Core.PropertyEditors;

/// <summary>
///     Represents the configuration for the multinode picker value editor.
/// </summary>
public class MultiNodePickerConfigurationEditor : ConfigurationEditor<MultiNodePickerConfiguration>
{
    public MultiNodePickerConfigurationEditor(IIOHelper ioHelper, IEditorConfigurationParser editorConfigurationParser)
        : base(ioHelper, editorConfigurationParser) =>
        Field(nameof(MultiNodePickerConfiguration.TreeSource))
            .Config = new Dictionary<string, object> { { "idType", "udi" } };

    /// <inheritdoc />
    public override Dictionary<string, object> ToConfigurationEditor(MultiNodePickerConfiguration? configuration)
    {
        // sanitize configuration
        Dictionary<string, object> output = base.ToConfigurationEditor(configuration);

        output["multiPicker"] = configuration?.MaxNumber > 1;

        return output;
    }

    /// <inheritdoc />
    public override IDictionary<string, object> ToValueEditor(object? configuration)
    {
        IDictionary<string, object> d = base.ToValueEditor(configuration);
        d["multiPicker"] = true;
        d["showEditButton"] = false;
        d["showPathOnHover"] = false;
        d["idType"] = "udi";
        return d;
    }
}

Property editors can be extended further to track entity references that may be selected or referenced inside the property editor. For example in the core of the CMS we have added this to numerous property editors.

A good example of this is the Media Picker. The CMS stores a reference to the selected media item, enabling the identification of content nodes that use that particular media item. This avoids it being accidentally deleted if it is being used.

When a content node is saved it will save the entity references as relations.

Viewing References

For Media Items

1. Go to the Media section.

2. Select a media item and click the Info tab.

For Content Nodes

1. Go to the Settings section.

2. Under the Relation Types folder, select Related Document relations and click Relations.

For Data Types

1. Go to the Settings section.

2. Expand the Data Types folder.

3. Select the Data Type you wish to view the references

4. Navigate to the Info tab.

Example

The following example shows how to implement tracking for the inbuilt CMS property editor Content Picker. It will always add a specific media reference, regardless of what value is picked in the content picker. In your own implementations, you will need to parse the value stored from the property editor you are implementing. You will also need to find any references to picked items in order to track their references.

using System;
using System.Collections.Generic;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Models.Editors;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Extensions;

namespace Umbraco.Web.PropertyEditors
{

     public class ExampleComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.DataValueReferenceFactories().Append<TrackingExample>();
        }
    }

    public class TrackingExample : IDataValueReferenceFactory, IDataValueReference
    {
        public IDataValueReference GetDataValueReference() => this;

        // Which Data Editor (Data Type) does this apply to - in this example it is the built in content picker of Umbraco
        public bool IsForEditor(IDataEditor dataEditor) => dataEditor.Alias.InvariantEquals(Constants.PropertyEditors.Aliases.ContentPicker);


        public IEnumerable<UmbracoEntityReference> GetReferences(object value)
        {
            // Value contains the raw data that is being saved for a property editor
            // You can then analyse this data be it a complex JSON structure or something more trivial
            // To add the chosen entities as references (as any UDI type including custom ones)

            // A very simple example
            // This will always ADD a specific media reference to the collection list
            // When it's a ContentPicker datatype
            var references = new List<UmbracoEntityReference>();
            var udiType = ObjectTypes.GetUdiType(UmbracoObjectTypes.Media);
            var udi = Udi.Create(udiType, Guid.Parse("fbbaa38d-bd93-48b9-b1d5-724c46b6693e"));
            var entityRef = new UmbracoEntityReference(udi);
            references.Add(entityRef);
            return references;
        }
    }
}

using System;
using System.Collections.Generic;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Models.Editors;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Extensions;

namespace Umbraco.Web.PropertyEditors
{

     public class ExampleComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.DataValueReferenceFactories().Append<TrackingExample>();
        }
    }

    public class TrackingExample : IDataValueReferenceFactory, IDataValueReference
    {
        public IDataValueReference GetDataValueReference() => this;

        // Which Data Editor (Data Type) does this apply to - in this example it is the built in content picker of Umbraco
        public bool IsForEditor(IDataEditor? dataEditor) => dataEditor?.Alias == Constants.PropertyEditors.Aliases.ContentPicker;


        public IEnumerable<UmbracoEntityReference> GetReferences(object? value)
        {
            // Value contains the raw data that is being saved for a property editor
            // You can then analyse this data be it a complex JSON structure or something more trivial
            // To add the chosen entities as references (as any UDI type including custom ones)

            // A very simple example
            // This will always ADD a specific media reference to the collection list
            // When it's a ContentPicker datatype
            var references = new List<UmbracoEntityReference>();
            var udiType = ObjectTypes.GetUdiType(UmbracoObjectTypes.Media);
            var udi = Udi.Create(udiType, Guid.Parse("fbbaa38d-bd93-48b9-b1d5-724c46b6693e"));
            var entityRef = new UmbracoEntityReference(udi);
            references.Add(entityRef);
            return references;
        }
    }
}