How To Build An Umbraco 7 Document Types In Visual Studio – USiteBuilder Explained

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

Download uSiteBuilder

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.

 

umbraco_usitebuilder_nuget

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’.  Next, make sure the class inherits from DocumentTypeBase. Any document types that you want to create using uSiteBuilder will need to derive from this class.  Following these instructions we should have a class that looks like this:

[DocumentType(Name = "News Document",
Description = "This is created with uSiteBuilder.")]    
public class NewsDocumentType : Vega.USiteBuilder.DocumentTypeBase     
{     
}   

Just this simple clas is enought 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:

umbraco_usitebuilder_creating_type

DocumentType Attribute

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

Properties

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:

[DocumentTypeProperty(UmbracoPropertyType.Textstring, 
Name = "Page Title", 
Tab = "Example", 
Description = "Page Title")]
public string PagePicker { get; set; }

When we look create an instance at the document type within Umbraco, you should now see the properties:

umbraco_usitebuilder_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

Conclusion

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.  To define your document types, simply create a class with some properties and decorate them with the appropriate attributes.  When you load your website it should load accordingly.

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

More Posts

3 replies

Trackbacks & Pingbacks

  1. […] as part of this guide.  If you want to know how to use uSitebuilder I have written this guide, How To Build An Umbraco 7 Document Types In Visual Studio – USiteBuilder Explained . To fully understand the project available from my GitHub that accompanies this article, I would […]

  2. […] Over the last few articles, I’ve discussed how to use uSiteBuilder in order to use classes to define your document types in How To Build An Umbraco 7 Document Types In Visual Studio – USiteBuilder Explained. […]

  3. […] article is a follow-up of, How To Build An Umbraco 7 Document Types In Visual Studio – USiteBuilder Explained . One of the aims of MVC is to be able to separate your presentation logic from your business logic. […]

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *