Declaring your property editor
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:
Name | Type | Required | Description |
---|---|---|---|
alias | string | Yes | A unique alias that identifies the property editor. |
name | string | Yes | The friendly name of the property editor, shown in the Umbraco backoffice. |
editor | object | Yes | This describes details about the editor. See the table below for further information. |
icon | string | No | A CSS class for the icon to be used in the Select Editor dialog - eg: icon-autofill . |
group | string | No | 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. |
isParameterEditor | boolean | No | Enables the property editor as a macro parameter editor. Can be either true or false (default). |
defaultConfig | object | No | Provides a collection of default configuration values, in cases the property editor is not configured or is used a parameter editor (which doesn't allow configuration). The object is a key/value collection and must match the prevalue fields keys. |
The
editor
object then has the following properties:Name | Type | Required | Description |
---|---|---|---|
view | string | Yes | This is the full path to the HTML view for your property editor. |
hideLabel | bool | Yes | If set to true , this hides the label for the property editor when used in Umbraco on a Document Type. |
valueType | object | No | This is the type of data you want your property editor to save to Umbraco. Possible values are STRING , JSON , DATETIME , TEXT and INT . Default is STRING . |
validation | object | No | Object describing required validators on the editor. |
isReadOnly | boolean | No | If set to true this makes the property editor read only. |
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"
]
}
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.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.
Name | Type | Required | Description |
---|---|---|---|
Alias | string | Yes | Gets the unique alias of the editor. |
EditorType |