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 elments 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.