Umbraco developer productivity with uSiteBuilder

After having used Umbraco for 2 years, I keep looking for ways to make my life even easier. As you may know, initial deployment of an Umbraco site is super easy. But then, a few weeks later, you've enhanced your site, added fields and macros and suddenly.. you have to remember and repeat those steps on your live server..

This is not what you want, it's labor intensive, prone to mistakes and there's no way to do any kind of continuous integration. The kind people at Vega IT Sourcing must have felt the same way and developed a solution for this called uSiteBuilder. 

The setup that I've chosen for this is a little bit different from the default that you get when out of the box. I've just downloaded and built the source of uSiteBuilder and from the "Vega.USiteBuilder\bin\Debug" folder I took the Vega.USiteBuilder.dll to use in my project.

My default Umbraco solution looks a bit like this:

More on how I set this up can be found in the Easily debug your custom Umbraco user controls in Visual Studio blog post. I still use that setup, except now in VS2010 and I only have 2 projects in there: the Umbraco site and my custom code organized in folders.

I reference the uSiteBuilder dll in the "SomeCompany.Extensions" project and then I'm ready to get started.

My post-build events look like this by the way:

XCOPY "$(ProjectDir)bin\SomeCompany.*" "$(ProjectDir)..\Umbraco\bin\" /y

XCOPY "$(ProjectDir)UserControls\*.ascx" "$(ProjectDir)..\Umbraco\UserControls\" /y

XCOPY "$(ProjectDir)Masterpages\*.master" "$(ProjectDir)..\Umbraco\masterpages\" /d /y

I really don't want to build my project every time I make a change to a masterpage file, I change my masterpages in the Umbraco site, not in the Extensions project. So for masterpages, I've added the extra /d parameter that will make sure only files that are newer in the Extensions project get copied to the website.

Master pages

Let's start with setting up a master page for the site, called Main, and a nested master page for the content of my TextPages.

Just right click in the Masterpages folder in the "SomeCompany.Extensions" project and create a new Masterpage called Main. The one thing we're going to change for now is setting the MasterPageFile to Umbraco's default MasterPage.

<%@ Master Language="C#" AutoEventWireup="true"

CodeBehind="Main.master.cs"

Inherits="SomeCompany.Extensions.MasterPages.Main"

MasterPageFile="~/umbraco/masterpages/default.master" %>

We'll get back to this Masterpage later.

Document Types

The most important feature of uSiteBuilder is that you can create your document types in code, instead of through the Umbraco interface. You just build a dll and drop it in your site's /bin folder. Once you do, the document type definitions that you've made get updated in Umbraco's database and, presto, no more manual deployments for document types!

As you might have read, I set up all of my sites using a SiteSettings node first and everything else goes under that. My goal is to get a document type structure that looks like this:

So let's get started with some code in DocumentTypes\SiteSettings.cs:

using Vega.USiteBuilder;



namespace SomeCompany.Extensions.DocumentTypes

{

[DocumentType(Name = "Site Settings", IconUrl = "house.png", Thumbnail = "developer.png", AllowedChildNodeTypes = new[] { typeof(TextPage) })]

public class SiteSettings : DocumentTypeBase

{

[DocumentTypeProperty(UmbracoPropertyType.ContentPicker, Name = "Homepage", Tab = "Settings", Description = "The item that you pick here will be the homepage of your site.")]

public string umbracoInternalRedirectId { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.TextboxMultiple, Name = "Google Analytics Code", Tab = "Settings", Description = "Paste your Google Analytics code here to get statistics of your website")]

public string googleAnalyticsCode { get; set; }

}

}

Make sure to go through the uSiteBuilder tutorials if you're not sure what's actually going on here.

Great, that's that sorted, we can continue to the PageSettings document type:

using Vega.USiteBuilder;



namespace SomeCompany.Extensions.DocumentTypes

{

[DocumentType(Name = "Page Settings", IconUrl = "folder.gif", Thumbnail = "folder.png", AllowedChildNodeTypes = new[] { typeof(TextPage) })]

public class PageSettings : DocumentTypeBase

{

[DocumentTypeProperty(UmbracoPropertyType.Textstring, Name = "Page title", Tab = "Page settings")]

public string pageTitle { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.Textstring, Name = "Meta title", Tab = "Page settings")]

public string metaTitle { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.Textstring, Name = "Meta description", Tab = "Page settings")]

public string metaDescription { get; set; }



[DocumentTypeProperty(UmbracoPropertyType.TrueFalse, Name = "Hide in navigation?", Tab = "Navigation")]

public string umbracoNaviHide { get; set; }

}

}

The PageSettings document type is just a set of generic properties that I am going to need on all of my publishable content pages. I would generally also add checkboxes for "Hide in sitemap", "Show in main menu", "Show in footer menu", etcetera.

I've cheated a little bit here, as you can see, I am allowing documents of type "TextPage" under the SiteSettings, but we haven't actually defined the TextPage yet. We'll fix that right now: 

using Vega.USiteBuilder;



namespace SomeCompany.Extensions.DocumentTypes

{

[DocumentType(Name = "Text page", IconUrl = "page.png", Thumbnail = "docWithImage.png", AllowedTemplates = new [] { "TextPage" }, DefaultTemplate = typeof (TextPage))]

public class TextPage : PageSettings

{

[DocumentTypeProperty(UmbracoPropertyType.RichtextEditor, Name = "Content", Tab = "Content", Description = "")]

public string bodyText { get; set; }

}

}

I am inheriting from the PageSettings class that I've just created so that TextPage will be nested under it.

Also, I have set the AllowedTemplates to TextPage, which doesn't exist yet. So it can now be created.

I've created a ContentPlaceHolder in Main.master:

<asp:ContentPlaceHolder Id="body" runat="server"></asp:ContentPlaceHolder>

Now I need to create the TextPage Masterpage by adding a new nested masterpage, based on Main.master:

We could just copy both masterpages (Main & TextPage) over to the site, but it will not do anything as we haven't told uSiteBuilder to pick it up and create the templates in Umbraco. 

So, as promised, we're getting back to Main.master. Go into the codebehind and change it to inherit from SiteSettings, like so:

public partial class Main : Vega.USiteBuilder.TemplateBase<DocumentTypes.SiteSettings>

A similar inherit is necessary for TextPage, but it will be from the TextPage document type. This will make sure that the docType knows how to find the template that it is allowed to use:

public partial class TextPage : Vega.USiteBuilder.TemplateBase<DocumentTypes.TextPage>

What can we not do?

There has been a lot of good news in this article so far. It's easy to create document types and templates and I haven't covered this, but it's also very easy to create UserControl macros from uSiteBuilder.

But uSiteBuilder is still incomplete at the moment. There's no way to create XSLT macros and you cannot predefine the sorting of tabs on your document types (although you can just sort them manually in Umbraco's interface, that works just fine). Furthermore, there's no way to create media types either.

As this is an open source project, I have good hopes that someone will create the missing bits as they need them. For now, I've been able to work around them really well though.

That being said, it only took me about an hour or to get started with it and even if I would still need to do some things manually, I can still gain a lot in productivity for the supported features, which is fantastic!

Putting it all together

This is a completely reusable way of creating your site structure. In your next project you can just start out with these basic document types and templates and build them out as needed.

Another nice advantage of having your document types as classes is that it's so easy to open them up and find the exact alias of a property to use in our Razor scripts, no more going to "Settings" > expanding "Document types" > going to the "Generic properties" tab and finding the alias.

Finally, as an added bonus, using Razor is really what makes it able for me to work with uSiteBuilder without problems, as you can create Razor macro's without.. creating a macro.

That's right, it's as easy as referring to a file. In your template, just insert a macro like this:

<umbraco:Macro FileLocation="~/macroScripts/MainMenu.cshtml" runat="server" />

So, now when you deploy your site, all you need to do is move around the changed files. Don't forget the "SomeCompany.Extensions.dll", together with "Vega.USiteBuilder.dll" it will start creating and modifying your docTypes and templates. 

Thanks to the great folks at Vega IT Sourcing for a truely awesome tool that makes my life much easier, I love it!