Blog: Creating Document Types in Umbraco Version 8
The new version of Umbraco introduced two new variations on the structural building block in Umbraco, the ‘Document Type’ - they can now be considered to be an ‘Is an Element type’ for defining the schema used in a repeating property editor, eg Nested Content and they can also now be ‘Allow Varying by culture’ to facilitate the new 1-1 multilingual options in V8 or both...
This poses a challenge to people who are new to Umbraco, or to me, someone who helps document Umbraco, and provides consultancy and support to development teams and needs to explain these concepts.
A ‘common language’ is essential when learning a new development skillset, and helping to form a ‘mental model’ in your head of how things hang together. Umbraco is generally very intuitive to work with but when it comes to architecting Document Types, it can be confusing - I mean what does a Document Type even mean? - (don’t think about it! - If you have been working with Umbraco for years - you take this phrase for granted, and if you start to question what it means… well you might start to doubt your own existence…)
So when I introduce and discuss this topic when working with development teams I tend to break down the ‘building blocks’ incrementally in size, and show how they all fit together within Umbraco’s architecture (the grand schema of things), I have diagrams... but there is a problem...
… not because the concepts are overly complex but because there aren’t defined ‘universal terms’ within Umbraco for the different types of things you can do with Document Types.
(I’ve had some degree of success in the past of using the vernacular of Atomic Design - see Lee and Marc’s talk at CG18 - to help people identify and remember differences between the options - but the mismatch with the terminology displayed in the menus in the backoffice can provide further confusion - particular now the new ‘element type’ gives off a scientific atomic scent of it’s own!)
Different DocType usages
Anyway broadly speaking there are:
- ‘Compositions’ - used to group properties together and reuse them in the construction of other Document Types
- ‘Elements’ - these new smaller schema configurations for defining repeating items in Nested Content
- ‘Folders’ - I suggest organising ‘each’ type of Document Type into separate folders
And Document Types themselves for creating Content Items which break down into:
- ‘Pages’ - the pages of the site, document types with defined templates - these pages have ‘Urls’
- ‘Components’ - items in the content tree without a template, they have no external Url - often to be ‘picked’ to share content across multiple pages.
NB: ‘Components’ here isn’t a proper ‘Umbraco term’ - some people call them widgets, or cogs or resources, pods, or blocks etc etc, and you start to see how not having a common domain language for things creates confusion…
The Big Confusion
So now we’ve established what the things are the big confusion for people new to Umbraco is how to create them, the existing Document Type Create menu looks like this:
You can see the scent that these three options give off isn’t an obvious match to the different types of 'things' that Document Types can be. You can’t use this menu to intuitively ‘discover’ the subtle flavours of Document Types at your disposal when modelling content. You have to be taught or learn by trial and error which option to use for which outcome.
- Document Type = Page (A Document Type With A Template)
- Document Type without a template = Component, Composition or Element Type (but there is the further checkbox to remember to tick)
- Document Type Collection = Is a ‘quick way’ of creating a Document Type with another Document Type permitted to be created underneath. (think 'News Section and News Article' - it’s annoying to create the News Section first, then the News Article then go back into the News Section to allow the News Article to be created underneath the News Section - this option tries to avoid this) But this is confusing to people new to Umbraco because ‘Document Type Collection’ sounds like a ‘special term’ in Umbraco, but it isn’t - you can’t find out about a Document Type Collection in documentation - yes it is annoying if you create the parent document type first, but it’s also really hard to ‘name’ two things at once… so you’ll find it’s not much of a time saver either!
- Folder = Folder
Simplification
It would be so much simpler if this menu reflected the different types of Document Types that can be created.
But here’s the great thing about Umbraco - you can extend and adapt it easily! What we currently have (think of them as ‘training wheels’ for people who are new to working with Umbraco) is a revised Create Menu - a ‘Super Doc Type Create Menu’ if you wish...
What's the thinking?
The first option, is arguably the most common, and the largest item that can be created from the menu (I think relative size of the outcomes of the Menu items as you move down the menu is important for understanding the concepts - I may be wrong about this)...
... Anyway ... the menu options says exactly what you get. A Document Type With a Template - its icon hints at the template part, it’s what you would use to create pages.
Next, a Document Type - some people prefer to use this option instead of the above (as they don’t like where Umbraco will automatically create the template) - but also this is used for creating components, content items that can be created in the content tree but without a template, (just 'slightly smaller' therefore conceptually, and so is the next item down in the Menu. I have overthought this!)
Element Type - having this option on the menu introduces the concept of Published Elements, you can see how important having the supporting descriptions on this menu are as the name 'Element Type' doesn't suggest what it is intended to be used for - choosing this option will automatically set the ‘Is Element Type’ flag to be true on the permissions tab. This is important, firstly: it saves time - but also the setting is often forgotten, this is because your ‘intent’ of creating an object of a certain type is focussed on this create menu - once the new Document Type is open for creation, there is nothing to guide you to the Permissions ‘Content app’ to change the underlying type to be an 'Element Type'.
(You’ll notice there is no mention of 'Vary by Culture' on this menu, even though the ‘Vary by Culture’ flag was added at the same time as the ‘Is Element Type’ flag and in the same place - it is 'conceptually a different thing' - all Document Types can ‘vary by Culture’ making one 'do so' does not change its 'fundamental type' - whereas the ‘Is Element Type’ setting does. (Same with ListView))
Composition - again I want people new to Umbraco to be able to discover the existence of the concept of using Compositions in the Document Type creation process, and the icon indicates they are ‘a fragment’ of something bigger, even though choosing this option has the same outcome as choosing ‘Document Type’ - it’s not always the case that providing ‘less’ options always makes an interaction ‘simpler’...
… but I have removed the ‘Document Type Collection’ option as this DOES make the menu clearer and simpler! for me, the benefits of being able to create two related Document Types at once is not great enough to justify including the option on this menu, particular for people who are new to Umbraco.
Folder - creates a folder!
Perfection
I’m not certain this is perfect!, everything can be continually improved and experimented with, but I feel that replacing the Create menu for Document Types with this Super Create menu reduces confusion during the learning process - and beyond! - I’m finding it pretty useful myself when consulting with clients on content modelling assignments, (but then I have always found I have to ‘double think’ what ‘Document Type without a Template’ means, to make super sure I choose the correct option).
Anyway we’ve made this available as an Umbraco Package, in case it may help others, and in the spirit of experimentation (this is a difficult interaction to improve without trying it in context) and we’re happy to accept pull requests to refine further, or discuss peoples ideas, or you could just use this to fork and design your own. It isn’t possible to update the menu in the Core of Umbraco at the moment, as there are ‘plans’ afoot for Document Types in the future, but right now, if you are creating Document Types in Umbraco V8 I think you can get a ‘super boost’ by installing this package.