Skip to content

Commit ba02541

Browse files
kjackjac
committed
Add detailed documentation for custom property editor migration to V14+
1 parent 72c8685 commit ba02541

File tree

2 files changed

+127
-1
lines changed

2 files changed

+127
-1
lines changed

‎15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ For example, it is hardly a server concern how many rows a text area should span
185185

186186
To this end, property editors have been split into two, individually reusable parts; the server implementation and the client implementation.
187187

188-
As a consequence, a property editor must now define both which client and server implementation to use. Details can be found in [Creating a Property Editor](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor) article.
188+
This change will likely impact custom Property Editors. See the [Migrate custom Property Editors to Umbraco 14](./migrate-custom-property-editors-to-umbraco-14.md) article for details.
189189

190190
* **Property value converters for package.manifest based property editors**
191191

‎15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-custom-property-editors-to-umbraco-14.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
description: >-
3+
This article will help you migrate custom Property Editors to Umbraco 14+
4+
---
5+
6+
# Migrate custom Property Editors to Umbraco 14+
7+
8+
{% hint style="info" %}
9+
This article _only_ applies to implementers of custom Property Editors - that is:
10+
11+
- Maintainers of Property Editor packages.
12+
- Site implementers who have built their own Property Editors.
13+
{% endhint %}
14+
15+
Umbraco 14 introduces a split between server-side and client-side Property Editor aliases. The reasoning behind this change is two-fold:
16+
17+
1. It allows server-side implementations to be reused for multiple client-side Property Editor UIs.
18+
2. It helps to ensure a better division between client-side and server-side responsibility.
19+
20+
## The migration impact for Property Editors
21+
22+
In the Umbraco source code, the change manifests as the `EditorUiAlias` property on `IDataType`.
23+
24+
When upgrading from Umbraco 13 to Umbraco 14+, we migrate all Data Types to ensure an `EditorUiAlias` value. For custom Property Editors, this migration is based on certain assumptions.
25+
26+
### Manifest based Property Editors
27+
28+
If the Property Editor is built with a [package manifest](https://docs.umbraco.com/umbraco-cms/13.latest/tutorials/creating-a-property-editor#setting-up-a-plugin), we:
29+
30+
1. Assign the package manifest `alias` to the Data Type `EditorUiAlias`, and
31+
2. Convert the Data Type `EditorAlias` to the alias of a core Data Editor, based on the `valueType` specified in the package manifest.
32+
33+
The following table contains the applied conversion from `valueType` to `EditorAlias`
34+
35+
| Property Editor `valueType` | Resulting `EditorAlias` |
36+
|-----------------------------|--------------------------|
37+
| `BIGINT` | `Umbraco.Plain.Integer` |
38+
| `DATE` | `Umbraco.Plain.DateTime` |
39+
| `DATETIME` | `Umbraco.Plain.DateTime` |
40+
| `DECIMAL` | `Umbraco.Plain.Decimal` |
41+
| `JSON` | `Umbraco.Plain.Json` |
42+
| `INT` | `Umbraco.Plain.Integer` |
43+
| `STRING` | `Umbraco.Plain.String` |
44+
| `TEXT` | `Umbraco.Plain.String` |
45+
| `TIME` | `Umbraco.Plain.Time` |
46+
| `XML` | `Umbraco.Plain.String` |
47+
48+
{% hint style="warning" %}
49+
**This might also impact Property Value Converters**
50+
51+
Property Value Converters for package manifest based Property Editors might be impacted by this migration.
52+
53+
It is common practice to pair a Property Editor to a Property Value Converter using the package manifest `alias`:
54+
55+
```csharp
56+
public bool IsConverter(IPublishedPropertyType propertyType)
57+
=> propertyType.EditorAlias.Equals("My.Editor.Alias");
58+
```
59+
60+
Since the migration moves the `alias` to `EditorUiAlias`, the Umbraco 14+ equivalent code looks like this:
61+
62+
```csharp
63+
public bool IsConverter(IPublishedPropertyType propertyType)
64+
=> propertyType.EditorUiAlias.Equals("My.Editor.Alias");
65+
```
66+
{% endhint %}
67+
68+
### Code based editors
69+
70+
If the Property Editor is built with a [Data Editor](https://docs.umbraco.com/umbraco-cms/13.latest/tutorials/creating-a-property-editor#setting-up-a-property-editor-with-csharp), we:
71+
72+
1. Assign the Data Editor `Alias` to the Data Type `EditorUiAlias`, and
73+
2. Retain the Data Type `EditorAlias` to as-is (which is the Data Editor `Alias`).
74+
75+
{% hint style="info" %}
76+
The Data Editor `Alias` is found in the `DataEditor` attribute:
77+
78+
```csharp
79+
[DataEditor("My.Editor.Alias")]
80+
public class MySuggestionsDataEditor : DataEditor
81+
{
82+
}
83+
```
84+
{% endhint %}
85+
86+
## The migration impact for porting Property Editor UIs
87+
88+
The [`umbraco-package.json`](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor#setting-up-a-plugin) file is a central component for extensions in Umbraco 14+, including Property Editor UIs.
89+
90+
To keep the Property Editor working with migrated properties, ensure that the `propertyEditorUi` extension is declared with:
91+
92+
1. The migrated value of `EditorUiAlias` as its `alias`, and
93+
2. The migrated value of `EditorAlias` as its `propertyEditorSchemaAlias` (found in the extension `meta` collection).
94+
95+
For example:
96+
97+
{% code title="umbraco-package.json" %}
98+
```json
99+
{
100+
"name": "My.Editors",
101+
"version": "1.0.0",
102+
"extensions": [
103+
{
104+
"type": "propertyEditorUi",
105+
"alias": "My.Editor.Alias",
106+
(...)
107+
"meta": {
108+
"propertyEditorSchemaAlias": "Umbraco.Plain.String",
109+
(...)
110+
}
111+
}
112+
]
113+
}
114+
```
115+
{% endcode %}
116+
117+
{% hint style="info" %}
118+
See also the [Creating a Property Editor](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor) article for guidance on building a Property Editor UI for Umbraco 14+.
119+
{% endhint %}
120+
121+
## Alternatives
122+
123+
If the Data Type migration yields an undesirable result, your have two options:
124+
125+
1. Manually change the `EditorAlias` and/or `EditorUiAlias` directly in the `umbracoDataType` table, or
126+
2. Create a custom migration to update the properties (see [this article](https://docs.umbraco.com/umbraco-cms/extending/database) for inspiration).

0 commit comments

Comments
 (0)