Skip to content

Commit 58feb99

Browse files
eshanrnheshanrnh
committed
2 parents 83b5e1b + e50b553 commit 58feb99

File tree

9 files changed

+391
-10
lines changed

9 files changed

+391
-10
lines changed

‎15/umbraco-cms/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
* [Version Specific Upgrades](fundamentals/setup/upgrading/version-specific/README.md)
2828
* [Upgrade from Umbraco 8 to the latest version](fundamentals/setup/upgrading/version-specific/upgrade-from-8-to-latest.md)
2929
* [Migrate content to Umbraco 15](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md)
30+
* [Migrate custom Property Editors to Umbraco version 14 and later](fundamentals/setup/upgrading/version-specific/migrate-custom-property-editors-to-umbraco-14.md)
3031
* [Migrate content to Umbraco 8](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-8.md)
3132
* [Minor upgrades for Umbraco 8](fundamentals/setup/upgrading/version-specific/minor-upgrades-for-umbraco-8.md)
3233
* [Upgrade to Umbraco 7](fundamentals/setup/upgrading/version-specific/upgrade-to-umbraco-7.md)

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

Lines changed: 4 additions & 4 deletions
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 version 14 and later](./migrate-custom-property-editors-to-umbraco-14.md) article for details.
189189

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

@@ -1062,7 +1062,7 @@ Remove `u.UseInstallerEndpoints();` from the `program.cs` file to avoid issues w
10621062

10631063
**Update code using Angular JS**
10641064

1065-
Angular JS has been removed in Umbraco 14. If you have extended your Umbraco project using Angular JS, it must be updated. for more information read the [Customize Backoffice](../../../../customizing/extend-and-customize-editing-experience.md) documentation.
1065+
Angular JS has been removed in Umbraco 14. If you have extended your Umbraco project using Angular JS, it must be updated. for more information read the [Customize Backoffice](../../../../customizing/overview.md) documentation.
10661066

10671067
**Deprecated property editors**
10681068

@@ -1401,7 +1401,7 @@ This is possible using Models Builder and through the inclusion of [core propert
14011401
14021402
To not break everybody's sites (the results of queries are different when PVCs are enabled), we disabled these PVCs by default.
14031403

1404-
Umbraco 7.6.0 also came with new pickers that store their data as a [UDI (Umbraco Identifier)](https://our.umbraco.com/Documentation/Reference/Querying/Udi). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.
1404+
Umbraco 7.6.0 also came with new pickers that store their data as a [UDI (Umbraco Identifier)](https://docs.umbraco.com/umbraco-cms/reference/querying/udi-identifiers). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.
14051405
14061406
We noticed that some new pickers also got their PVC's disabled when the configuration setting was set to false (`<EnablePropertyValueConverters>false</EnablePropertyValueConverters>`).
14071407

@@ -1552,7 +1552,7 @@ and
15521552

15531553
Umbraco Forms 6.0.0 has been released to be compatible with Umbraco 7.6. It is a new major version release of Forms primarily due to the strict dependency on 7.6+. If you are using Forms, you will need to update it to version 6.0.0
15541554

1555-
There are [**important Forms upgrade documentation that you will need to read.**](https://docs.umbraco.com/umbraco-forms/installation/version-specific.md#version-4-to-version-6).
1555+
There are [**important Forms upgrade documentation that you will need to read.**](https://github.com/umbraco/UmbracoDocs/blob/umbraco-eol-versions/11/umbraco-forms/installation/version-specific.md).
15561556
15571557
**Courier**
15581558

‎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 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.

‎16/umbraco-cms/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
* [Version Specific Upgrades](fundamentals/setup/upgrading/version-specific/README.md)
3030
* [Upgrade from Umbraco 8 to the latest version](fundamentals/setup/upgrading/version-specific/upgrade-from-8-to-latest.md)
3131
* [Migrate content to Umbraco 15](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md)
32+
* [Migrate custom Property Editors to Umbraco version 14 and later](fundamentals/setup/upgrading/version-specific/migrate-custom-property-editors-to-umbraco-14.md)
3233
* [Migrate content to Umbraco 8](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-8.md)
3334
* [Minor upgrades for Umbraco 8](fundamentals/setup/upgrading/version-specific/minor-upgrades-for-umbraco-8.md)
3435
* [Upgrade to Umbraco 7](fundamentals/setup/upgrading/version-specific/upgrade-to-umbraco-7.md)

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,7 @@ For example, it is hardly a server concern how many rows a text area should span
224224

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

227-
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.
227+
This change will likely impact custom Property Editors. See the [Migrate custom Property Editors to Umbraco version 14 and later](./migrate-custom-property-editors-to-umbraco-14.md) article for details.
228228

229229
* **Property value converters for package.manifest based property editors**
230230

@@ -1101,7 +1101,7 @@ Remove `u.UseInstallerEndpoints();` from the `program.cs` file to avoid issues w
11011101

11021102
**Update code using Angular JS**
11031103

1104-
Angular JS has been removed in Umbraco 14. If you have extended your Umbraco project using Angular JS, it must be updated. for more information read the [Customize Backoffice](../../../../customizing/extend-and-customize-editing-experience.md) documentation.
1104+
Angular JS has been removed in Umbraco 14. If you have extended your Umbraco project using Angular JS, it must be updated. for more information read the [Customize Backoffice](../../../../customizing/overview.md) documentation.
11051105

11061106
**Deprecated property editors**
11071107

@@ -1440,7 +1440,7 @@ This is possible using Models Builder and through the inclusion of [core propert
14401440
14411441
To not break everybody's sites (the results of queries are different when PVCs are enabled), we disabled these PVCs by default.
14421442

1443-
Umbraco 7.6.0 also came with new pickers that store their data as a [UDI (Umbraco Identifier)](https://our.umbraco.com/Documentation/Reference/Querying/Udi). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.
1443+
Umbraco 7.6.0 also came with new pickers that store their data as a [UDI (Umbraco Identifier)](https://docs.umbraco.com/umbraco-cms/reference/querying/udi-identifiers). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.
14441444
14451445
We noticed that some new pickers also got their PVC's disabled when the configuration setting was set to false (`<EnablePropertyValueConverters>false</EnablePropertyValueConverters>`).
14461446

@@ -1591,7 +1591,7 @@ and
15911591

15921592
Umbraco Forms 6.0.0 has been released to be compatible with Umbraco 7.6. It is a new major version release of Forms primarily due to the strict dependency on 7.6+. If you are using Forms, you will need to update it to version 6.0.0
15931593

1594-
There are [**important Forms upgrade documentation that you will need to read.**](https://docs.umbraco.com/umbraco-forms/installation/version-specific.md#version-4-to-version-6).
1594+
There are [**important Forms upgrade documentation that you will need to read.**](https://github.com/umbraco/UmbracoDocs/blob/umbraco-eol-versions/11/umbraco-forms/installation/version-specific.md).
15951595
15961596
**Courier**
15971597

‎16/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 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.

‎17/umbraco-cms/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
* [Version Specific Upgrades](fundamentals/setup/upgrading/version-specific/README.md)
3030
* [Upgrade from Umbraco 8 to the latest version](fundamentals/setup/upgrading/version-specific/upgrade-from-8-to-latest.md)
3131
* [Migrate content to Umbraco 15](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md)
32+
* [Migrate custom Property Editors to Umbraco version 14 and later](fundamentals/setup/upgrading/version-specific/migrate-custom-property-editors-to-umbraco-14.md)
3233
* [Migrate content to Umbraco 8](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-8.md)
3334
* [Minor upgrades for Umbraco 8](fundamentals/setup/upgrading/version-specific/minor-upgrades-for-umbraco-8.md)
3435
* [Upgrade to Umbraco 7](fundamentals/setup/upgrading/version-specific/upgrade-to-umbraco-7.md)

0 commit comments

Comments
 (0)