x First time here? Check out the FAQ
Join us a the Umbraco event of the year - get your Codegarden 14 early bird ticket today

Working with document types

    What are Document Types?

    Document Types are the heart of the content structure of umbraco. They define which properties the content elements have in detail, which properties are mandatory, which properties are optional and which data types the properties are of. Also they define which templates can or must be used for the content elements and which document types can occur below each content element.

    The problem for understanding document types and their relationships to templates, content hierarchy and generic properties are complex. So we are going step by step, looking for each relationship in detail and at the end we are putting the pieces together

     

    Document Types in a new installation

    In an empty umbraco installation you have an empty content tree. So  if you want to add a new content element you will do a right click on the content, select 'Create'. But the occuring dialog is completely empty (like the pic below). Neither the name is filled nor any document type is present and clicking the create button will give you an error.

    So the first questions are:

    • Why is there no Document Type after a newinstallation?
    • And why can't a content element be created without Document Type?

    The answer to the first question is: umbraco is installed completely empty. So you can create the website from scratch with no ballast from any prepared objects. If you want to have a sample site installed use some of the website wizards like the umbracoWebsiteWizard or Warren Buckley's WebsiteWizard.

    The answer to the second question is: The architecture of umbraco does not allow to create a content element without document type because the document types define which properties, templates and hierarchy will be used for the content elements. We will see this in the next praragraphs. For now we have to accept that this is a restriction from umbraco.

    Properties

    When you are creating a Document Type you are defining fields that will be used to enter data.  These fields are called Properties in umbraco.  Properties are defined on the "Generic Properties" tab.  Creating properties is not the first step, first you will want to create Tabs which are explained next.  Properties have metadata (a term used to define data that is used to define or describe an object).  Items in the metadata include: Name, Alias, Type, Tab, and others.  Tip: If you create a new page but cannot enter the content you expect, check and ensure you have created a Property for it and that you are looking at the tab the property was set to.

    • Name - This item is the user friendly name of the property.  The typical example used in many tutorials for this is "Content".  This is the text that the user will see describing the property during content editing.
    • Alias - This item is the text used by umbraco during the GET_ITEM calls.  Basically this means anytime you want to refer to the property within code such as a template you will use the Alias.
    • Type - This item is a selection from a list of Data Type objects.  Data Types are not the same as those in computer programming.  A Data Type in umbraco is an editor type associated to the Property.  A common Type used is "Rich Text Editor"; selecting this type will display a rich text editing control to the user during content editing of this Property.
    • Tab - This item allows you to select which Tab this property will be presented to the user during content editing.  This list is populated from tabs created in the Tabs section.  General Properties is a selection in the list, this is a little confusing, but it is actually referring to the Properties tab that is displayed during content editing.  The Properties tab is a good place to define properties you want to use as metadata fields.

     

    Tabs

    Document Types organize Properties on the screen by using Tabs so the first thing you will want to do when creating a Document Type is create one or more tabs.  Later in this book we will walk through the steps of creating a Document Type so many of these items will be clearer.  Tabs only have one piece of metadata: Name which is the text display used to identify the tab and is the text displayed in the Tab.

     

    Structure

    The Structure tab is where you control the hierarchy of your site.  Structure allows you to determine which Document Types can be nested as children to the one you are creating.  This means that if a user tries to create a new page of content under the Document Type, they will only have options of the Document Types checked in the Document Type's Structure.  Tip: If you try to create a new page of content under another and you cannot add a type you expect, check the structure tab of the parent Document Type and ensure the expected type has been checked.

     

    Info

    While the Info tab is the first tab on the Document Type, it is less important than the others.  This is because the Info tab primarily entails the display options for the Document Type while the other tabs define the Document Type itself.  Metadata set on the Info tab include: Name, Alias, Icon, Thumbnail, Description, Allowed Templates, and Default Template, this data is described below.

    • Name - This item is the user friendly name of the Document Type.  This is the text that the user will see in the type selection drop down list on the Create Page dialog.  Tip: If you see Document Types in the drop down list that you didn't intend, you should modify the structure of the parent page's Document Type.
    • Alias - This item is the text used by umbraco.
    • Icon - This item is a selection from a list of images.  The icon is the image that is displayed in the content tree.
    • Thumbnail - Do not confuse the Thumbnail with the Icon.  The Thumbnail is a larger image that shows on the Create Page dialog.
    • Description - The description text is displayed on the Create Page dialog.  This is a good place to inform the user about what the Document Type is intended for.
    • Allowed Templates - Document Types only define the content data not how that content is displayed.  Displaying the content is the job of the Template.  A Document Type could be used in more than one template.  The Allowed Templates allows you to control which templates are allowed to access this Document Type.  This is important because it lets you display the same data differently in different areas of your site.
    • Default Template - The default template is the template used by default when creating a page of this Document Type.