Umbraco is widely known as "The Friendly CMS." But, as much as I love Umbraco, I think a more accurate label might be "The Potentially Friendly CMS." While Umbraco provides the foundation and tools for a friendly content editor experience, it's up to us as developers to fully utilise these resources to make the backoffice experience intuitive and enjoyable for our content editors.
I realised how essential this is during a conversation with a prospective client. They were frustrated with their Umbraco 8 site, calling the backoffice confusing and hard to use—a far cry from the user-friendly CMS I know Umbraco can be. After listening to their concerns, it became clear that whoever originally built their site completely overlooked the importance of the Content Editor's experience. Was this on purpose? Did they not care? Or did they simply not know and not realise?
Either way, this was eye-opening and led me to think more deeply about how we, as developers, can utilise Umbraco’s built-in features and some fantastic community packages to make the CMS experience genuinely enjoyable for content editors.
What we will cover
We will look at what tools and features Umbraco provides out of the box, what third-party packages we can utilise, and how we can ensure that the developers on our teams make “considering the content editor” part of their workflow.
A lot of the things we’ll be covering will likely be mostly common sense to an experienced Umbraco developer, but with a lot of these things, if you're not told about them, then you wouldn’t know; so hopefully this article will be useful to you, even if it is just a refresher!
Structure
Firstly, let's look at what tools Umbraco provides for structuring our Content.
DocTypes & MediaTypes
DocTypes, as you know, are the backbone of our Umbraco websites, they can be pages, settings, list views, reusable items etc.. they can be many things in many different ways! This is why it is up to us, as developers, to make sure that we create a DocType structure that is easy to understand, easy to navigate and makes sense to the people managing the content, not just us the developers. We should aim to create clear, organised content structures by grouping fields logically, using tabs, using intuitive naming conventions, and setting up only the necessary fields to not overload our editors with “too many options”.
Three principles that I like to remember when creating doctypes (and when coding in general) are:
KISS - “Keep It Simple Stupid”
Keep the DocTypes as simple as possible, don’t overload them with complexity.
YAGNI - “You Aren't Gonna Need It”
Don’t create properties that you don’t need right now.
If this is a simple brochureware site, that will get edited once and not touched in years, does it really need a fully fledged grid editor?
DRY - “Don’t Repeat Yourself”
Don't duplicate properties (use compositions!) and don’t force the Content Editor to enter the same information twice.
Compositions
Compositions are awesome, they’re a great way of creating a reusable set of properties that can be used across multiple other doctypes; this then has the benefit of only defining these properties once, and avoids the headache of having to maintain duplicate properties across multiple DocTypes!
Some good examples of a Composition would be SEO properties, default properties like a Block Grid/List, standard page settings, navigation settings, hero banner properties etc..
And the best bit? Compositions can share Tabs and Groups! This means that if multiple compositions have a “Content” Tab or a “Content” Group, then their properties will get merged into a single “Content” Tab/Group on the DocType that composes them.
For example:
Here is a “Block List” composition, that has a Block List inside of a Group and a Tab named “Content”.
When composed, its property gets merged into the Content groups that already exist, and the Block List now sits alongside the existing property.
And here’s an example of an SEO composition.
Tip
You can use the Property/Group/Tab’s Sort Order to enforce which ones appear first, last or somewhere between.
In your Models Builder generated models, compositions are implemented as interfaces on your model:
This is awesome, as it means you can do stuff like this to easily figure out if an IPublishedContent has your composition properties:
if (Model is IHeroBannerComposition heroBanner)
{
var title = heroBanner.HeroBannerTitle;
}
Nested DocTypes
If we have compositions, why would we ever nest a DocType?
Nesting DocTypes is a good way to make “variants” of a DocType, for example, if we have a LandingPage, we could make a NewsLandingPage and a BlogLandingPage variant.
The benefits of nesting like this are:
The nested DocTypes inherit the parent’s properties
We can add additional properties to the nested DocTypes
We can add a unique icon to help differentiate the nested DocTypes
Additionally, for this example, we can make it so that the News and Blog landing pages use a ListView, whereas the default Landing page does not.
And, on your Models Builder generated models, nested DocType models extend their parent models (rather than implementing an interface like compositions do).
DocType Permissions
Another thing to take into consideration is DocType creation permissions, as we all know, we need to add DocTypes as “Allowed child node types” to create them in the tree; but for DocTypes where there will only ever be a certain amount (like homepage, news landing page, blog landing page, settings etc…) do we really need to keep those permissions if the content editors will never need to create them?
Probably not, so it makes sense to remove them; and in our example, that would mean that the “Create a Content item” menu would go from this:
Now the Content Editors aren’t flooded with options to create nodes that they will never need to create!
But what if this is a multi-site setup, and we need to let the content editors create some required nodes when adding a new site? Well, if you ever need to add “required” nodes, then you should probably do that automatically in a content-saved notification (more on that later).
Tabs and Groups
No one wants to be presented with a giant overwhelming wall of properties, so we should make sure that we use Tabs and Groups to organise the properties into a structure that makes sense.
Naturally, this will be specific and different to each project, but I would suggest that you:
Use Tabs to group properties by usage (e.g. Content, SEO, Page Settings etc..)
Move lesser-used properties away from the main content
Make sure the most commonly used properties are easily available, in the first tab, so that the content editor doesn't have to go hunting for them.
And finally, don't go overboard, if you start ending up with loads of tabs and groups, then you should consider if you really need them, can they be simplified, or should they be split out into a different DocType altogether?
Labels, Aliases and Descriptions
Now that’s the structure out of the way, let's take a look at how we can make using our DocTypes much nicer!
Tip
Aliases are for the developers, and Labels are for the Content Editors!
One thing I notice junior developers doing, when they’re new to Umbraco, is making the labels and aliases identical when they probably shouldn’t be; now yes, most of the time they probably will be, but sometimes it is a good idea to set the label as something that makes sense to the editor, and the alias as something that makes sense to the developer.
For example, do the labels need to be prefixed with “Hero Banner” in our Hero Banner Composition?
They’re already grouped into a group named “Hero Banner”, so the contextual information that these are “Hero Banner” properties is already there, so we can probably remove that prefix from the labels to make it look a bit more tidy and easier to read:
The alias, on the other hand, should keep the prefix, as we don’t have the same “group” context when we access the properties on the strongly typed model.
So next time you’re creating a property, stop and think, does this label make sense to a content editor who doesn’t know how this site is built?
And don’t skip on the descriptions! Whilst not every property needs a description, a lot do, so don't forget to add them, and be sure to write them in a content editor-friendly way.
For example, if a property is used as a fallback, or overrides a different one, then that should definitely be noted in its description. And for a Block List, you can consider adding some “tips” on how they can use it, especially if the content editors are new to Umbraco.
Also, did you know you can do some basic markdown in the descriptions too? Well, you can! The Umbraco Learning Base YouTube account has a good video demoing this feature: https://www.youtube.com/watch?v=QAZ8ZZerbZQ
Here’s an example in v13’s AngularJS backoffice:
And here’s the example in v15’s Bellissima backoffice:
At the time of writing, it appears that neither the “bold” nor the “collapsible content“ markdown is working correctly in the v15 backoffice.
Note
After publication, it was brought to my attention that the Markdown syntax had actually changed in the new backoffice, but the docs had simply not yet been updated to reflect this.
Therefore, in v15, you should use `<details>` instead of dashes to make collapsible regions in descriptions. (the dashes were also what was causing the entire description to become bold)
Remember to keep the descriptions short, as the UI can get very messy with longer descriptions, therefore if you need to write a more in-depth description, then you should consider using the Editor Notes feature on the Contentment package (more on that later!)
Don’t forget the icons!
Be sure to use icons to make it easy for your content editors to distinguish the different content types, so they can quickly find what they’re looking for.
For example, if we just used the default icon, everything would look the same. Can you easily tell which pages are content pages, landing pages, or form pages in the first screenshot below?
You can also take it one step further and use colours to group related content types.
Extending and Customising the Backoffice
Ok, so we’ve got our structure in place and made it pretty, let’s now have a look at how we can further tailor the backoffice to our client’s needs, by extending it!
Custom Property Editors
Umbraco has an extensive library of property editors that can make life easier for content editors. With options ranging from pickers and dropdowns to rich text, block lists and block grid editors, the variety enables you to choose tools that are intuitive and suited to the content being created.
But sometimes, you may need something that isn't there by default, and luckily creating your own custom property editor is fairly simple! I won't be covering exactly how to do that here, but you can find some good guides in the Umbraco docs on how to get started:
But what I will do is show you some examples of some simple custom property editors, that I made in the past, that may serve as some inspiration:
Choosing the style of a Call To Action Block
Choosing the type of heading in a Heading block
Choosing the position of the image in a Text Block
Could these have been dropdowns or a radio list? Yes, they definitely could have been, but the custom buttons and icons make them look better and feel a bit nicer. It’s like that dusting of icing sugar on top of a sponge cake, you don't need it, but it really adds to the experience.
Custom Dashboards & Sections
Umbraco also provides the ability to create custom sections and dashboards, which are incredibly useful for providing extra functionality to the client and tailoring the backoffice to their needs.
Again, I won’t go into the details on how to create these, but the Umbraco docs are a very good starting point:
Here are a few that I and my team at Method4 have created for clients:
Extracts Manager that allows the client to download extracts of data, from the site, as Excel spreadsheets for internal auditing purposes.
Data Import tool that allows the client to periodically update data on the site.
Umbraco Migration Tool that I created to help us easily migrate websites from Umbraco 7/8 to Umbraco 10+.
Custom Login Screen
Customising the login screen is another great way of making a client’s Umbraco backoffice feel more personal and tailored. It’s a small thing, but it really does add that nice “cherry on top” to your projects!
Umbraco’s documentation has a good guide on how to do this:
Here are two examples of customised login screens that I have done:
Trydan Gwyrdd Cymru (screenshot used with permission)
My personal website
Notification Handlers
Notification handlers are super useful, especially if you want to automate the creation of nodes in the backoffice!
For example, let’s imagine you have a client project that has multiple sites within a single Umbraco installation, and each one of those sites has a few required nodes that need to exist beneath the Homepage node for the sites to function (e.g. settings node, news landing page, blogs landing page, search page etc…)
It wouldn't be fair to expect the Content Editors to remember to create these nodes every time they make a new site, what if they create them in the wrong place? What if we removed the create permissions as we did earlier in this article?
Well then, that’s where a custom notification handler would come in handy! We could create a “ContentSavedNotification” handler, check if the node being saved is a new homepage node and create the required nodes beneath it if they don’t already exist!
Here you can see that the "required" nodes get created when a new Homepage node is saved.
Tip
We could also create a “ContentDeletingNotification” handler to block the deletion of important nodes!
3rd Party Packages
Let's have a look at some third-party packages that I think complement the backoffice and make the content editor experience that little bit more friendlier and useful!
The welcome dashboard is the first thing your content editors see, and the default one is mostly useless to them, so let's replace it with something much more useful!
The Dashboard package replaces the default Content Dashboard with a much more useful overview of what’s been happening on the site. It shows you the recent activities of all backoffice users, lists your recent activity, lists any unpublished content that don’t have schedules, and displays a few stats about the site.
Content is a brilliant package, that adds a ton of super useful property editors to really tailor your backoffice to your client's needs!
Admittedly, I haven’t used many of the property editors Contentment provides, so I will just concentrate on the Editor Notes feature, which I have used a lot.
Editor notes are awesome, they provide you with a really nice way of including extra information into your DocTypes, to help explain functionality and/or provide useful tips to your content editors.
Here are some that I’ve added to my projects:
A note on a Landing Page to explain how child pages are rendered.
Notes on media items to give tips on writing Alt Text, image attributions, and to provide links to useful resources.
A note on a Heading block to give tips on when to use which type of heading.
The Block Preview package is super, it allows you to re-use your frontend views and styles as the backoffice block previews, completely eliminating the need to maintain a completely separate set of preview files! (maintaining separate AngularJS based previews, was a right pain!)
I first used this package on a project earlier this year, and I was blown away at how easy it was to get good-looking previews in my Block Lists!
One point to bear in mind is that there is no visual indicator between the blocks by default, there is just a small menu on the top right that appears on hover; therefore, unless you style your blocks in a way that makes them easily identifiable as separate items, then they can be hard to differentiate from each other.
This is something that I the developer didn’t really notice, but after watching my client use the backoffice, I noticed they were struggling to differentiate between the different blocks in the list; therefore, I went and added an outline around the block previews, to help differentiate the blocks, along with a label denoting the type of block.
I achieved this by creating a Tag Helper which uses a super useful extension, added by the Block Preview package, to check if the current request is a block preview request or not; I then add a css class to add the outline and inject a span for the label. The two spacer divs are to get Umbraco’s “insert between” UI to show nicely between the two blocks.
public class BlockItemTagHelper : TagHelper
{
[HtmlAttributeNotBound]
[ViewContext]
public ViewContext ViewContext { get; set; }
private HttpRequest Request => ViewContext.HttpContext.Request;
public string BlockName { get; set; }
public override void Process(TagHelperContext context, TagHelperOutput output)
{
output.TagName = "div";
if (Request.IsBlockPreviewRequest())
{
output.AddClass("block-preview", HtmlEncoder.Default);
output.PreContent.SetHtmlContent($"<span class=\"block-preview__name\">" +
$"{BlockName}" +
$"</span>");
output.PreElement.SetHtmlContent("<div class=\"block-preview-spacer\"></div>");
output.PostElement.SetHtmlContent("<div class=\"block-preview-spacer\"></div>");
}
}
}
And then all of my Block views simply use this tag helper as their containing divs!
How do you ensure that your devs consider the backoffice experience?
It’s very easy to overlook some of the points I’ve gone over here, so to help ensure that doesn’t happen to you could consider adding some of these to your Definition of Done, and check for them when reviewing PRs!
Does the Pull Request contain new DocTypes and properties? Then as part of the review, you should:
Check if they have appropriate labels and descriptions
Check if they made use of existing compositions
Check if the DocType is structured nicely using groups and tabs
Also, involve the content editors!
The best way to know if your Umbraco setup is editor-friendly is to ask the people using it!
You should consider involving your client’s content editors in the development process and get them to try out what you’re building, so they can provide feedback early on! If you're following an Agile development, like Scrum, then get them involved in the Sprint reviews. If you run backoffice training sessions with them, watch how they use the backoffice, as you can then see where they may be struggling.
Additionally, some issues might only come to light after using the setup with real production content, therefore you might want to consider scheduling a feedback session with the content team a few months after launch.
Conclusion
By putting in the time and effort to think about the needs of content editors, we can make Umbraco truly live up to its "Friendly CMS" label. From structured content organization, using compositions, groups and tabs, to a more intuitive welcome dashboard and custom property editors, small tweaks can make a huge difference in the experience for those using the CMS daily. Remember, the friendliest CMS isn’t just one that developers love to build in; it’s one that content editors love to use.
So next time you start an Umbraco project, keep the content editor front and center and ensure that the experience you’re building is as friendly as the CMS itself promises to be.
