This is part five in a series about common tasks you'll encounter when upgrading Umbraco 13 to 17. In this part, we’ll look at updating Property Editors and Property Value Converters.
When upgrading several packages, one area that caused confusion was Property Editors. In Umbraco 17 there is a much clearer separation between the UI in the backoffice and the data handling and validation on the backend (C#).
Because of this change, Umbraco introduced migrations that convert existing Data Types (which are essentially instances of a Property Editor) to the new format. In Umbraco 13 a Data Type only referenced a single editor alias, but in Umbraco 17 it contains two: an editor alias (backend) and an editor UI alias (frontend). This makes it possible, for example, to use multiple interchangeable UIs that work with the same underlying data.
Why won't my property editor work anymore?
After upgrading my database to Umbraco 17 I ran into a couple of issues:
- How does Umbraco know that it should use my newly created Property Editor UI for existing properties?
- Why does Models Builder suddenly return a
JsonDocumentinstead of my customVideoPlayerValueConverterModel?
The answer lies in understanding what the migration from Umbraco 13 to 14+ actually does and what you need to do with the result. This post walks through that process.
This blog explains how you can update your Property Editors to work in Umbraco 17 without having to create a custom migration. It also helps to read the , for example:
using Umbraco.Cms.Core.PropertyEditors;
namespace YourProjectName;
[DataEditor(
alias: "Suggestions editor",
name: "Suggestions",
view: "/App_Plugins/Suggestions/suggestion.html",
Group = "Common",
Icon = "icon-list")]
public class Suggestions : DataEditor
{
public Suggestions(IDataValueEditorFactory dataValueEditorFactory)
: base(dataValueEditorFactory)
{
}
}
Defining a Property Editor in code gives you more control over validation and how the data is stored.
The resulting database records
When you create a Data Type in Umbraco 13 that uses a Property Editor, the resulting database record is almost identical for both approaches. Each Data Type simply stores a property editor alias and configuration in the umbracoDataType table.
Updating the code
Once you understand what the migration produced in the database, updating the code becomes much clearer.
Creating and registering the Property Editor UI
With the new backoffice introduced in Umbraco 14+, the UI part of your Property Editor needs to be recreated because AngularJS is no longer supported.
After creating the UI, you need to register it. I won't go into the details of building a Property Editor UI here (the documentation covers that), but the aliases you use during registration are important.
Based on the migration result:
aliasshould match PropertyEditorUiAlias
propertyEditorSchemaAliasshould match PropertyEditorAlias
For example:
export const manifests: Array<UmbExtensionManifest> = [
{
type: 'propertyEditorUi',
alias: "proudnerds.videoplayer.editor",
name: "Proud Nerds video player property editor",
js: () => import("./proud-nerds-video-property-editor-ui.element"),
meta: {
label: "Video player",
icon: "icon-play",
group: "Proud Nerds",
propertyEditorSchemaAlias: "Umbraco.Plain.Json",
settings: {
properties: [
...
]
}
}
}
Updating the DataEditor (if it already exists)
If your editor already had a DataEditor implementation, you can continue using it, but it needs to be updated for Umbraco 17.
Most of the implementation remains similar to Umbraco 13. The main difference is that several parameters have been removed from the DataEditor attribute because of the clearer separation between UI and backend logic.
// Umbraco 13
[DataEditor(
alias: "proudnerds.videoplayer.editor",
name: "Video Player",
view: "/App_Plugins/VideoPlayer/videoplayer.html",
Group = "Proud Nerds",
Icon = "icon-play")]
public class VideoPlayerEditor : DataEditor
...
// Umbraco 17
[DataEditor("proudnerds.videoplayer.editor")]
public class VideoPlayerEditor : DataEditor
...
Updating the Property Value Converter (if needed)
If you used the manifest-only approach in Umbraco 13, there is a good chance your Property Value Converter no longer works.
During migration, the EditorAlias for the video editor changed from:
proudnerds.videoplayer.editor
to:
Umbraco.Plain.Json
So if your Property Value Converter checks the editor alias, it will no longer match:
public override bool IsConverter(IPublishedPropertyType propertyType) =>
propertyType.EditorAlias.Equals("proudnerds.videoplayer.editor");
The simplest fix is to check the EditorUiAlias instead:
public override bool IsConverter(IPublishedPropertyType propertyType) =>
propertyType.EditorUiAlias.Equals("proudnerds.videoplayer.editor");
This is not entirely semantically correct, but it is often the easiest solution without introducing additional migrations. After this, your Property Editor will work as expected again and the models builder will use your custom model instead of the generic JsonDocument.
Done
Once you understand how the Property Editor migration works, it becomes much easier to determine which aliases to use in umbraco-package.json and what code changes are required after upgrading.
The concepts themselves are straightforward, but the migration can be confusing the first time you encounter it. Hopefully this overview helps clarify what is happening behind the scenes.
EditorUiAlias or not?
Earlier I mentioned that checking EditorUiAlias inside the IsConverter method of a Property Value Converter is not entirely correct from a semantic point of view.
A Property Value Converter operates on the data stored in the database and converts that to something else to put in the cache. A Property Editor UI is only the interface used to edit that data. In fact, multiple UIs could theoretically exist for the same underlying editor.
Because of that, checking EditorUiAlias introduces some risk. If a different UI were introduced for the same editor, your converter might no longer match the correct data. Checking EditorAlias is the safest way to guarantee you are handling the expected data structure.
That said, in many real-world scenarios a Property Editor has exactly one UI and one DataEditor that always belong together. If you fully control the implementation, checking EditorUiAlias can be a pragmatic and perfectly workable solution that avoids writing additional migrations.
Opinions on this tend to differ. Some developers strongly prefer to always check EditorAlias for correctness, while others consider EditorUiAlias acceptable when the editor and UI are tightly coupled. In the end, the choice depends on how strictly you want to follow the separation between UI and data.
SOCIAL SHARE CARD GENERATOR