Property editor composition rewrite for Umbraco 17 #7685

Luuk1983 · 2025-12-02T16:02:26Z

📋 Description

This is a rework of the pages that combined describe the part that make up a Property Editor. It covers an overview page, a page about the Property Editor UI and the Property Editor Schema.

I did not touch the Data Sources article that's also part of the Property Editor composition. This is a quite niche concept and I felt like that article is good enough for now (discusses with Mads).
I created new articles for the extensions of the property editor ui and property editor schema under the extension type section. These articles describe all settings into detail. I felt like the Property Editor articles would get too bloated if they also needed to deal with the complete configuration options. BEWARE!! These two articles (although verified against the source code) are AI generated.

📎 Related Issues (if applicable)

Fixes #7603

✅ Contributor Checklist

I've followed the Umbraco Documentation Style Guide and can confirm that:

Code blocks are correctly formatted.
Sentences are short and clear (preferably under 25 words).
Passive voice and first-person language (“we”, “I”) are avoided.
Relevant pages are linked.
All links work and point to the correct resources.
Screenshots or diagrams are included if useful.
Any code examples or instructions have been tested.
Typos, broken links, and broken images are fixed.

Product & Version (if relevant)

Umbraco 17

Deadline (if relevant)

…ir architecture, and configuration settings

…ce clarity on architecture and custom implementations

…s on Property Editor settings, configuration, and validation handling for improved clarity and usability

…tion

AndyButland

This is great @Luuk1983. I just had a few comments on the wording in a few places where I though it was a either a little repetitive or vague, but mostly seems to me you and your AI helper have done a really good job here. I don't see any factual issues at all, so just have a few tidying up suggestions.

17/umbraco-cms/customizing/property-editors/composition/property-editor-schema.md

17/umbraco-cms/customizing/property-editors/composition/README.md

17/umbraco-cms/customizing/property-editors/composition/property-editor-schema.md

…tion

…thub.com/Luuk1983/UmbracoDocs into feature/7603_property_editor_composition

Luuk1983 · 2025-12-08T15:08:07Z

@AndyButland, I processed your comments (and fixed the reviewdog warnings). If the changes are OK, could you please approve the PR? :)

AndyButland

Yes, thanks for the updates @Luuk1983 - approving now.

Updated the README.md to enhance clarity and structure of the Property Editors section, including definitions and best practices.

sofietoft

Thanks for the PR @Luuk1983 !

Really great content. It is very well described, also for someone like me, who isn't that technical! 👏

I'm half-way through the review, still missing the two articles in the "Property Editors" section. I'll get those done on Monday.

Here are some notes for the articles in the Extending Overview section:

In the "Property Editor Schema", I've made suggestions to move the two warnings from "Important Notes".
If you agree with this suggestion, then we could take the note about the default property editor schemas out of the hint, and place it directly below the "Important Notes" heading instead, as tne only content there.
What do you think?
There is also a case of this, in the "Property Editor UI" article.

Hope it all makes sense! 🙏

sofietoft · 2025-12-12T09:34:30Z

17/umbraco-cms/customizing/extending-overview/extension-types/property-editor-schema.md

+{% 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 %}


How about we move this up to the "Manifest Properties" heading around line 74? That way you get this warning before you start working with the properties.

I would really like to go on your insights. Warnings are always a balance. Sometimes you need to explain something before a warning makes sense (even though it might be a little 'late' for the warning). Sometimes it's better to warn beforehand.

I think that if you felt like it should be moved while reading this document for the first time, than we should move it. I've read this document so many times now that a fresh perspective from someone like you is much more valuable. So please go ahead and change it :)

sofietoft · 2025-12-12T09:35:27Z

17/umbraco-cms/customizing/extending-overview/extension-types/property-editor-schema.md

+{% 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 %}


How about we move this up to the "Settings Structure" heading around line 117? That way you get this warning before you start working with the properties.

I would really like to go on your insights. Warnings are always a balance. Sometimes you need to explain something before a warning makes sense (even though it might be a little 'late' for the warning). Sometimes it's better to warn beforehand.

I think that if you felt like it should be moved while reading this document for the first time, than we should move it. I've read this document so many times now that a fresh perspective from someone like you is much more valuable. So please go ahead and change it :)

sofietoft · 2025-12-12T09:45:37Z

17/umbraco-cms/customizing/extending-overview/extension-types/property-editor-ui.md

+{% hint style="warning" %}
+The `propertyEditorSchemaAlias` in the manifest **must match** an existing Property Editor Schema alias. This connects the UI to the backend data handling and validation.
+{% endhint %}


I think it's makes more sense to have this warning where the "propertyEditorSchemaAlias" is defined the article. Then you get the information when you need it.

This also allows us to take the information from the next hint out, and add it as plain text.

I would really like to go on your insights. Warnings are always a balance. Sometimes you need to explain something before a warning makes sense (even though it might be a little 'late' for the warning). Sometimes it's better to warn beforehand.

I think that if you felt like it should be moved while reading this document for the first time, than we should move it. I've read this document so many times now that a fresh perspective from someone like you is much more valuable. So please go ahead and change it :)

sofietoft · 2025-12-12T09:55:30Z

17/umbraco-cms/customizing/property-editors/composition/README.md

+## Advanced
+
+This chapter covers advanced scenarios. It is intended for developers who understand the basics of Property Editors and want to explore more sophisticated patterns.


What is the chapter referred to here? Is that this article, or sub-articles?
Is it possible to replace "This chapter" with what "This chapter" is referring to? 🤔

The 'this chapter' is the 'advanced' chapter you are in right now :) You could also call it 'the advanced section/chapter' or 'This advances section/chapter'.

Ah, alright. Wouldn't it be better to have this mentioned at the top of the article? Then anyone new to this subject, will know not to start here.
Also, are there any more beginner friendly sections we could refer to instead?

I think the fact that it's called advanced and is introduced with a text that explains that is't for advanced scenerio's is pretty clear.

The thing is, documentation about the Property Editor Data Sources is a very advanced topic that Mads wrote. It wasn't under 'advanced' before, so I tried to make it clear that unless you know what you are doing and have mastered the rest, you might want to look into this, otherwise skip it. So the advanced heading makes sense I think.

So if you think it's still not clear enough, go ahead and change it, although I'm not sure what to change it in :)

Also I don't think this should keep this PR from being delayed. It's an important topic and the current pages on the documentation still have the 'this is a work in progress' banner I think. So I think there is some urgency to get this through.

I am in no way trying to delay this. If this should be expedited quicker, I'm more than happy to hand it over to one of my colleagues, as I'm not back to working full time just yet.

My concern with this, was just that the article doesn't mention it being advanced until you get to this note. So, it was just a suggestion to move it closer to the start of the article 🙏

Removed duplicate warning about propertyEditorSchemaAlias and updated related notes.

Refactor and clarify the Property Editor Schema documentation, improving readability and consistency in terminology. Also revised some minor grammar.

sofietoft · 2025-12-15T08:53:10Z

17/umbraco-cms/customizing/property-editors/composition/property-editor-schema.md

+You can define settings on both the Property Editor Schema and the Property Editor UI. It's good practice to define settings that have impact on the data (like validation rules) on the Property Editor Schema. Settings that only impact the UI should be set on the Property Editor UI.
+ {% endhint %}


The way this warning is currently phrased, it sounds more like information to me.
I agree that it would make sense as a warning, but then I think the actual warning part of the message should be defined first 🤔

What do you think?

sofietoft · 2025-12-15T09:45:47Z

17/umbraco-cms/customizing/property-editors/composition/README.md

+## Advanced
+
+This chapter covers advanced scenarios. It is intended for developers who understand the basics of Property Editors and want to explore more sophisticated patterns.


I am in no way trying to delay this. If this should be expedited quicker, I'm more than happy to hand it over to one of my colleagues, as I'm not back to working full time just yet.

My concern with this, was just that the article doesn't mention it being advanced until you get to this note. So, it was just a suggestion to move it closer to the start of the article 🙏

Updated the Property Editor UI documentation for clarity and consistency, including improvements in phrasing and structure throughout the text.

Luuk Peters and others added 9 commits November 19, 2025 12:18

Refactor code structure for improved readability and maintainability

fc11417

Refactor code structure for improved readability and maintainability

41f8938

Enhance README.md with detailed explanations of Property Editors, the…

5879f13

…ir architecture, and configuration settings

Refactor code structure for improved readability and maintainability

666cc2c

Refactor README.md for Property Editors: streamline content and enhan…

ddd84e9

…ce clarity on architecture and custom implementations

Enhance README.md and property-editor-ui.md: add detailed explanation…

99e8a36

…s on Property Editor settings, configuration, and validation handling for improved clarity and usability

Merge branch 'umbraco:main' into feature/7603_property_editor_composi…

85d2264

…tion

Add Property Editor Schema and UI documentation; remove unused image

77e5f61

Fix typos and improve clarity in Property Editor documentation

069d43b

sofietoft added the community/docs-team label Dec 3, 2025

AndyButland reviewed Dec 3, 2025

View reviewed changes

Luuk1983 and others added 6 commits December 8, 2025 15:18

Merge branch 'umbraco:main' into feature/7603_property_editor_composi…

99ffe33

…tion

Processed feedback on PR

e32c461

Merge branch 'feature/7603_property_editor_composition' of https://gi…

4e04dec

…thub.com/Luuk1983/UmbracoDocs into feature/7603_property_editor_composition

Fix review dog warnings

945cdd3

Another round of ReviewDog fixes

7070eb8

Last ReviewDog update, AI can't count...

da0dbe2

AndyButland approved these changes Dec 9, 2025

View reviewed changes

sofietoft added 3 commits December 12, 2025 10:38

Fix formatting and punctuation in property editor schema

a1e3b8a

Fix formatting and punctuation in property-editor-ui.md

5aa32fd

Revise README for Property Editors clarity

6892c3c

Updated the README.md to enhance clarity and structure of the Property Editors section, including definitions and best practices.

sofietoft reviewed Dec 12, 2025

View reviewed changes

sofietoft added 3 commits December 15, 2025 09:11

Moved warnings to the relevant sections

0412127

Refactor warnings and notes in property-editor-ui.md

ee7cf11

Removed duplicate warning about propertyEditorSchemaAlias and updated related notes.

Revise Property Editor Schema documentation

bcb1702

Refactor and clarify the Property Editor Schema documentation, improving readability and consistency in terminology. Also revised some minor grammar.

sofietoft reviewed Dec 15, 2025

View reviewed changes

Refine Property Editor UI documentation

297590b

Updated the Property Editor UI documentation for clarity and consistency, including improvements in phrasing and structure throughout the text.

		## Advanced

		This chapter covers advanced scenarios. It is intended for developers who understand the basics of Property Editors and want to explore more sophisticated patterns.

		You can define settings on both the Property Editor Schema and the Property Editor UI. It's good practice to define settings that have impact on the data (like validation rules) on the Property Editor Schema. Settings that only impact the UI should be set on the Property Editor UI.
		{% endhint %}

Property editor composition rewrite for Umbraco 17 #7685

Are you sure you want to change the base?

Property editor composition rewrite for Umbraco 17 #7685

Uh oh!

Conversation

Luuk1983 commented Dec 2, 2025

📋 Description

📎 Related Issues (if applicable)

✅ Contributor Checklist

Product & Version (if relevant)

Deadline (if relevant)

Uh oh!

AndyButland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Luuk1983 commented Dec 8, 2025

Uh oh!

AndyButland left a comment

Choose a reason for hiding this comment

Uh oh!

sofietoft left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants