When you start building a new enterprise-level project, you want to be able to do things like storing your data-types in source control, unit testing your code and use features like continuous integration to automatically deploy your code.
Creating and defining your document types manually within Umbraco, prevents you from doing these sorts of things. For example, if you have a development environment and you create a document type and template via the CMS. When you come to deploy your code into production, you're stuck with a dilemma.
You can't simply copy the database onto production because, in the real world, content editors will be constantly updating content, creating new pages etc... on the live site and your dev environment database might be out of date. Swapping databases on a live environment would involve taking your website offline and the rollback process is also problematic.
You definitely don't want to have to manually copy your document types by hand, so what do you do? A better approach is to be able to create your document type outside of Umbraco itself, in a class. When you come to deploying to production you simply copy over your views and document types and the majority of the hard work is done for you.
Luckily, a free open-source extension for Umbraco has been build, open-source and free of charge called uSiteBuilder. In today's tutorial, I am going to cover how to install uSiteBuilder and create a document type in visual studio with a couple of basic properties.
First, if you visit the uSiteBuilder website here you can download uSiteBuilder officially. Luckily, there is also a uSiteBulider port on Nuget that does everything for you. If you open up visual studio and go to package manager, if you type in 'usite' you should see two options appear. I've only ever used the port done by 'Vega' as it's got the largest download count.
How Does It Work?
So before we dive into code, I'll give a quick overview of what we're going to do. First, we are going to create a C# class that will define our document types. The class will be decorated by a special attribute, that will define various bits of meta-data that Umbraco needs. After that, we can then define properties like you would a normal POCO, decorated with more special Umbraco attributes to define how those properties will be created within Episerver. Now it's time to roll our sleeves up and get stuck in.
Creating A Document Type
First, create a folder to store your document types in. I usually create a folder called 'DocumentTypes'. In here, create a new c# class and call it whatever you want your document type to be called (Note we cannot define the Alias). I am going to call my document type 'NewsDocumentType'. Ensure the class inherits from DocumentTypeBase. Any document types that you want to create using site builders will need to derive from this class. Following these instructions we should have a class that looks like this:
Just this simple class is enough to create a document type in Umbraco, don't believe me... load up Umbraco and look in Settings -> Document Types. You should see the newly created document type:
The way this 'magic' works is, as you might have guessed, done through the 'DocumentType' attribute that decorates the class. If you have ever used Episerver CMS, for example, this mechanism is exactly the same as how you would define a page type.
Decorate the class, define the meta-data and let uSiteBuilder do the rest. It's probably a good idea to go over what type of meta-data in Umbraco you can set via the 'DocumentType' attribute.
- Name: The Name that will be displayed in Umbraco
- Description: The Description that will be displayed in Umbraco
- AllowedTemplates: The templates that will be associated with the document type
- DefaultTemplate: The default template
- IconUrl : The icon that will be displayed int he 'Create New' tab
- AllowedChildNodeTypes : The document types that can be created under this one
After we have the basics of our document type defined, the next step is to define some properties to store data against. To do this, we need to look at the 'DocumentTypeProperty' attribute. Like, 'DocumentType' we need to decorate any property we want to be created within the document type with it. 'DocumentTypeProperty' has several properties that define how the property will be created in Umbraco. An example of how a property will look like in code can be seen below:
When we look create an instance at the document type within Umbraco, you should now see the properties:
The DocumentType Property give us a lot flexibility, including:
- UmbracoPropertyType: The type of Umbraco property to use. The UmbracoPropertyType includes, Label, Upload, TextboxMultiple, Textstring, RichtextEditor, Numeric, TrueFalse, CheckboxList, Dropdown, DatePicker, Radiobox, DropdownMultiple, FolderBrowser, ApprovedColor, DatePickerWithTime, Other, ContentPicker, MediaPicker, MemberPicker, SimpleEditor, UltimatePicker, RelatedLinks, Tags
- Name: The name that will be displayed by the property in the editor
- Tab: The tab that the property will be rendered in
- Description: The description that will be displayed by the property in the editor
There you have it, today we've covered the benefits of being able to define your Umbraco 7 document types in code. Luckily for us, we can use uSiteBuilder to do this for us. Installing 'uSiteBuilder' is very easy via Nuget so I recommend that you give it a try