Document Types

Before setting out to build a web site, you should ask yourself the question: What kind of information do I want to persist and subsequently publish? Can I group the information into several different types of information? Examples could be Product, Person, Location, Article et cetera.

A Document Type in Umbraco defines one specific type of information. A document type contains all the placeholders for all the different parts of the information within that information type. So we would have Document Types for the above Product, Person, Location, Article et cetera. By the way, "Document Type" is an unfortunate choice of words. Documents remind me of the representation of information, not of the information itself. But this convention has been standard in the community and will probably never change.

Here is an example of the possible structure of a Document Type Person:

  • First Name
  • Middle Name
  • Last Name
  • Nickname
  • Email
  • Linkedin Address
  • Birthday
  • Biography
  • Rating.

Conditions and restrictions

When defining a Document Type, you can add specific conditions (such as: this piece of information is required, or may only be a date). Make an effort to be as precise as you can be; this will help editors to enter uniform information and generally improve your data quality.

For this particular example, I would set the following conditions:

  • First Name: Text. Required; an upper bound to the length of the input (say, 80 characters). It is very unlikely that a person would have such a long First Name. Most likely, any input over 80 characters in this particular field would be an attempt to test (or attack) the website. 
  • Middle Name: Text. Optional; an upper bound to the length of the input (say, 80 characters)
  • Last Name: Text. Required; an upper bound to the length of the input (say, 80 characters)
  • Nickname: Text. Optional. When empty, the application will concatenate First, Middle and Last Names
  • Email: Text. Required, checking if the entered information is a valid email address
  • Linkedin Address: Text. Optional. If entered, should be a valid URL.
  • Birthday: Optional. But if entered, should be a valid DD/MM or DD/MM/YYYY date.
  • Biography: Text. Optional with an upper bound of 4.000 characters.
  • Rating: A single precision number between 0 and 10. May not be edited. Will be calculated by the application (e.g. number of contributions or the feedback on these contributions).

A note on the length of texts and the type of numbers: in theory there is very little need to minimize text lengths but you have to ask yourself the question: am I planning to interact with other systems? If so, will we provide information to the other system or vice versa? What are the conditions that we need to meet? 

Generic vs specific

There is a choice to be made between a very generic approach (all information is basically just of a Document Type web page) and a very specific approach (each type of information deserves its own document type). Keep in mind that maintaining Document Types requires an effort. So look for a healthy balance. When you end up defining more than 20 Document Types, take a step back and see if they are really all necessary.

Quite often we also want to create overviews of products, people, locations, articles et cetera. For these specific overview pages you may want to create additional document types. In the example above we might need document types Products, Persons, Locations, Articles. Of course, there is no explicit convention to name a grouping document type to the plural of the document type name, but if it helps the website manager to keep an good overview, why not?

All of the above can - and should - be done as much as possible at the very start of the project and before the actual implementation in Umbraco. All of the above is really CMS-agnostic.

After having identified all Information Types check to see if you have been consistent with naming conventions and if the order of the individual information bits is logical and consistent. And check for the last time for redundancies.

Assembling a Document Type in Umbraco

The next step is to further prepare your definitions by considering which information you want to be grouped logically together and by defining names for these groups. So far, we have done nothing that is specific to Umbraco. This above process should be followed regardless of the CMS you plan to work with.

Umbraco has something called Compositions which is very much worth looking into, but we will put them aside for the moment and return to them in another blog post. 

So, we have groups with several pieces of information (properties) in them. We now have to select the appropriate editors for each of these properties. As most editors can be configured, start thinking of re-use of editors right away.   

Umbraco gives you the opportunity to enter custom labels for each of the pieces of information, as well as a description. Make sure you select labels and descriptions that will be understood by an editor without technical knowledge. The good news is you can change them later.

Umbraco does something else: when you create a Document Type, it will create a unique and, importantly, unchangeable, alias for this Document Type. This alias is used for all kinds of internal references between items. Say, a Document is of a certain Document Type. If the reference would be on the basis of the Document Type Name, changing the name would break the reference. Hence the unique and unchangeable alias. So when you create a new Document Type, you had better know a pretty good name for it, because the generated alias is going to be there forever (and you might look pretty silly if the alias were something like documenttype1). 

Aliases are generated in Dromedary or Lower Camel Case. So "Person" becomes "person" and "Dried Fruit" becomes "driedFruit". 

As with Document Types, the individual information pieces also have a name and description that are mutable, but the generated alias is immutable.

As you add a new property to a Document Type, you have to select an appropriate editor. Many different editors exist. For example:

 

The Common Editors are pretty predictable in their purpose and behavior. Most other content management systems have these editors as well. A textbox has only one configurable property: the maximum length of the string that may be entered. A text area has two: the maximum length of the string that may be entered and the number of rows that will be displayed when editing a content item of this particular Document Type.

Assume we have a Document Type Blogpost and you select a text box, you will see the name and the configuration options. In another blogpost we will say more about this Name characteristic.

So, pick the appropriate editor for each property of your Information Type (explore them all if you have the opportunity), group them together in logical groups (again from the perspective of an editor who will work with the system), and configure each editor properly.

One warning comes to mind. Developers tend to think that there is no proper editor for the property that must be edited. Umbraco facilitates creating custom editors. But make sure you first explore the standard available properties first. Nothing to match your needs? Check the community next. Still nothing, then you have a case for building a custom editor. And why not do the community a favor by giving your editor back to the Umbraco community?

Done! Or maybe not, as some other aspects are important as well.

We will zoom in on them in the next blog post.

Next chapter