|
| 1 | +--- |
| 2 | +description: >- |
| 3 | +This article helps you migrate custom Property Editors to Umbraco 14 and later. |
| 4 | +--- |
| 5 | + |
| 6 | +# Migrate custom Property Editors to Umbraco version 14 and later |
| 7 | + |
| 8 | +{% hint style="info" %} |
| 9 | +This article applies _only_ 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 | +## 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 and later, Umbraco automatically migrates all Data Types to include 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): |
| 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 and later 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` 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 | +## 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 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 and later. |
| 119 | +{% endhint %} |
| 120 | + |
| 121 | +## Alternatives |
| 122 | + |
| 123 | +If the Data Type migration yields an undesirable result, you 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 the [Creating a Custom Database Table](https://docs.umbraco.com/umbraco-cms/extending/database) article for inspiration. |
0 commit comments