Skip to content

Property editor composition rewrite for Umbraco 17 #7685

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Luuk1983 wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Property editor composition rewrite for Umbraco 17 #7685

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fc11417
Refactor code structure for improved readability and maintainability
Nov 19, 2025
41f8938
Refactor code structure for improved readability and maintainability
Nov 24, 2025
5879f13
Enhance README.md with detailed explanations of Property Editors, the…
Nov 24, 2025
666cc2c
Refactor code structure for improved readability and maintainability
Nov 25, 2025
ddd84e9
Refactor README.md for Property Editors: streamline content and enhan…
Dec 1, 2025
99e8a36
Enhance README.md and property-editor-ui.md: add detailed explanation…
Dec 2, 2025
85d2264
Merge branch 'umbraco:main' into feature/7603_property_editor_composi…
Luuk1983 Dec 2, 2025
77e5f61
Add Property Editor Schema and UI documentation; remove unused image
Dec 2, 2025
069d43b
Fix typos and improve clarity in Property Editor documentation
Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions 17/umbraco-cms/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,8 @@
* [Modals](customizing/extending-overview/extension-types/modals/README.md)
* [Custom Modals](customizing/extending-overview/extension-types/modals/custom-modals.md)
* [Modal Route Registration](customizing/extending-overview/extension-types/modals/route-registration.md)
* [Property Editor Schema](customizing/extending-overview/extension-types/property-editor-schema.md)
* [Property Editor UI](customizing/extending-overview/extension-types/property-editor-ui.md)
* [Property Value Preset](customizing/extending-overview/extension-types/property-value-preset.md)
* [Sections](customizing/extending-overview/extension-types/sections/README.md)
* [Section](customizing/extending-overview/extension-types/sections/section.md)
Expand Down
4 changes: 2 additions & 2 deletions 17/umbraco-cms/customizing/extending-overview/extension-types/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,8 +159,8 @@ These are the current types of UI Extensions:
| packageView | A package view is an optional view that can be shown in the "Packages" section of the Backoffice. The user can navigate to this view to see more information about the package and to manage it. |
| previewAppProvider | A preview app provider is a provider that can be used to provide a preview app for the Save and Preview action on a document. |
| propertyAction | A property action is a button that can be added to the property actions menu. |
| propertyEditorSchema | A property editor schema is a model that describes a Data Editor and its properties from the backend to the UI. It is used by Property Editor UIs. Read more about [Property Editors](../../property-editors/). |
| propertyEditorUi | A property editor UI is a UI component that can be added to content types. It is used to render the UI of a Data Editor. Read more about [Property Editors](../../property-editors/). |
| propertyEditorSchema | A property editor schema is a model that describes a Data Editor and its properties from the backend to the UI. It is used by Property Editor UIs. Read more about [Property Editor Schema](property-editor-schema.md). |
| propertyEditorUi | A property editor UI is a UI component that can be added to content types. It is used to render the UI of a Data Editor. Read more about [Property Editor UI](property-editor-ui.md). |
| searchProvider | A search provider is a provider that can be used to provide search results for the search bar in the Backoffice. |
| searchResultItem | A search result item is a component that can be added to the search results. |
| theme | A theme is a set of styles that can be added to the Backoffice. The user can select their preferred theme in the current user modal. |
Expand Down
214 changes: 214 additions & 0 deletions ...co-cms/customizing/extending-overview/extension-types/property-editor-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,0 +1,214 @@
---
description: Reference documentation for the propertyEditorSchema extension type
---

# Property Editor Schema

The `propertyEditorSchema` extension type registers a Property Editor Schema in the Umbraco backoffice. A Property Editor Schema defines the server-side data contract for a property editor, including data storage type, validation rules, and configuration options.

{% hint style="info" %}
For detailed information about implementing Property Editor Schemas with C# classes (`DataEditor` and `DataValueEditor`), see the [Property Editor Schema Guide](../../property-editors/composition/property-editor-schema.md).
{% endhint %}

## Manifest Structure

The manifest defines how the schema appears in the backoffice and what configuration options are available when creating Data Types.

### Basic Example

A minimal schema manifest specifies which Property Editor UI should be used by default:

```typescript
import type { ManifestPropertyEditorSchema } from '@umbraco-cms/backoffice/property-editor';

export const manifest: ManifestPropertyEditorSchema = {
type: 'propertyEditorSchema',
name: 'Text Box',
alias: 'Umbraco.TextBox',
meta: {
defaultPropertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
},
};
```

### Example with Configuration

If your Property Editor Schema has configurable settings, define them in the manifest to enable administrators to configure the Data Type in the backoffice:

```typescript
export const manifest: ManifestPropertyEditorSchema = {
type: 'propertyEditorSchema',
name: 'Decimal',
alias: 'Umbraco.Decimal',
meta: {
defaultPropertyEditorUiAlias: 'Umb.PropertyEditorUi.Decimal',
settings: {
properties: [
{
alias: 'placeholder',
label: 'Placeholder text',
description: 'Enter the text to be displayed when the value is empty',
propertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
},
{
alias: 'step',
label: 'Step size',
description: 'The increment size for the numeric input',
propertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
},
],
defaultData: [
{
alias: 'step',
value: '0.01',
},
],
},
},
};
```

## Manifest Properties

The `propertyEditorSchema` manifest can contain the following properties:

### Required Properties

| Property | Type | Description |
| -------- | ------ | --------------------------------------------------------------------------- |
| type | string | Must be `"propertyEditorSchema"` |
| alias | string | Unique identifier for the schema. Must match the C# `DataEditor` alias. |
| name | string | Friendly name displayed in the backoffice |
| meta | object | Metadata object containing schema configuration (see Meta Properties below) |

### Optional Properties

| Property | Type | Description |
| -------- | ------ | -------------------------------------------------------------- |
| weight | number | Ordering weight. Higher numbers appear first in lists. |
| kind | string | Optional kind identifier for grouping related schemas together |

## Meta Properties

The `meta` object contains the following properties:

### Required Meta Properties

| Property | Type | Description |
| ---------------------------- | ------ | --------------------------------------------------------------------- |
| defaultPropertyEditorUiAlias | string | The alias of the default Property Editor UI to use with this schema |

### Optional Meta Properties

| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------ |
| settings | object | Configuration settings for the property editor (see Settings below) |

## Settings Structure

The `settings` object defines what configuration options appear when creating or editing a Data Type:

```typescript
settings: {
properties: PropertyEditorSettingsProperty[];
defaultData?: PropertyEditorSettingsDefaultData[];
}
```

### Settings Properties Array

Each object in the `properties` array defines a configuration field:

| Property | Type | Required | Description |
| ------------------------ | ------ | -------- | ------------------------------------------------------------------------------ |
| alias | string | Yes | Unique identifier. Must match the C# `ConfigurationEditor` property name. |
| label | string | Yes | Display label for the configuration field |
| description | string | No | Help text shown below the label |
| propertyEditorUiAlias | string | Yes | The Property Editor UI to use for editing this configuration value |
| config | object | No | Optional configuration to pass to the Property Editor UI |
| weight | number | No | Optional ordering weight for the configuration field |

### Settings Default Data Array

Each object in the `defaultData` array provides default values:

| Property | Type | Required | Description |
| -------- | ------- | -------- | --------------------------------------------- |
| alias | string | Yes | The alias of the configuration property |
| value | unknown | Yes | The default value for this configuration |

## Complete Example

```typescript
import type { ManifestPropertyEditorSchema } from '@umbraco-cms/backoffice/property-editor';

export const manifest: ManifestPropertyEditorSchema = {
type: 'propertyEditorSchema',
name: 'Suggestions Editor',
alias: 'My.PropertyEditor.Suggestions',
weight: 100,
meta: {
defaultPropertyEditorUiAlias: 'My.PropertyEditorUi.Suggestions',
settings: {
properties: [
{
alias: 'maxChars',
label: 'Maximum characters allowed',
description: 'The maximum number of allowed characters in a suggestion',
propertyEditorUiAlias: 'Umb.PropertyEditorUi.Integer',
weight: 10,
},
{
alias: 'placeholder',
label: 'Placeholder text',
description: 'Text displayed when the field is empty',
propertyEditorUiAlias: 'Umb.PropertyEditorUi.TextBox',
weight: 20,
},
{
alias: 'disabled',
label: 'Disabled',
description: 'Disables the suggestion button',
propertyEditorUiAlias: 'Umb.PropertyEditorUi.Toggle',
weight: 30,
},
],
defaultData: [
{
alias: 'maxChars',
value: 50,
},
{
alias: 'placeholder',
value: 'Write a suggestion',
},
{
alias: 'disabled',
value: true,
},
],
},
},
};
```

## Important Notes

{% hint style="warning" %}
The `alias` in the manifest **must exactly match** the alias used in the C# `DataEditor` attribute. The alias is the only connection between the server-side schema implementation and the client-side manifest.
{% endhint %}

{% hint style="warning" %}
Configuration property aliases in `settings.properties` **must match** the property names defined in your C# `ConfigurationEditor` class. If they don't match, configuration values won't be properly passed to the backend for validation and storage.
{% endhint %}

{% hint style="info" %}
Umbraco ships with several [default property editor schemas](../../../tutorials/creating-a-property-editor/default-property-editor-schema-aliases.md) that you can use without creating custom C# classes.

Check warning on line 206 in 17/umbraco-cms/customizing/extending-overview/extension-types/property-editor-schema.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.Editorializing] Consider removing 'several' as it can be considered opinionated.

Raw Output:
{"message": "[UmbracoDocs.Editorializing] Consider removing 'several' as it can be considered opinionated.", "location": {"path": "17/umbraco-cms/customizing/extending-overview/extension-types/property-editor-schema.md", "range": {"start": {"line": 206, "column": 20}}}, "severity": "WARNING"}
{% endhint %}

## Related Documentation

* [Property Editor Schema Guide](../../property-editors/composition/property-editor-schema.md) - Learn about implementing the C# classes (`DataEditor` and `DataValueEditor`)
* [Property Editor UI Extension Type](property-editor-ui.md) - Reference for the Property Editor UI extension type
* [Creating a Property Editor Tutorial](../../../tutorials/creating-a-property-editor/) - Step-by-step guide to building a custom property editor
* [Adding Server-Side Validation](../../../tutorials/creating-a-property-editor/adding-server-side-validation.md) - Tutorial on implementing validation in your schema
Loading
Loading