How to Create Multiple Unique Sites in One Installation Using Theming and the Umbraco Grid

by Heather Floyd

Ever since looking at Shannon's "Articulate" Blog package, I have been intrigued by the possibilities for "theming" in Umbraco. Not to provide a Wordpress-like "plug-n-play" templated site, but to host multiple different websites inside the same Umbraco install.

Why would you want to do that? Well, in cases where it makes sense, the advantage of maintaining a single codebase is huge - along with the efficiency provided by not having to duplicate 90% of website files (the Umbraco core components) and have multiple databases in order to host different websites.

Last year I had the opportunity to explore the possibilities of a themed installation when Scandia decided to move the uWestFest website to Umbraco Cloud hosting.

Previously, each year a new website installation was created to host that year's conference website, and between conferences a static "splash page" was put up at the uWestFest.com domain. What if we could consolidate every year’s website into a single installation? Then we could continue to have the old sites online, for archival purposes, as well as facilitate faster development of the new site each year. Theming was the answer.

Is Your Project a Good Fit for Theming?

If you are considering using theming in your Umbraco installation, I suggest you think about whether the project requirements are a good fit. To arbitrarily stuff 10 different websites into a single install just because you can might cause more problems than it will solve.

The best application is one where you have visual variations on essentially the same sort of content. In the case of uWestFest, the conference has similar content each year: A schedule of sessions, biographies of speakers, info about ticket sales, venue, sponsorship, etc. Each year we have different visual branding, though, with sites looking and behaving in completely different ways.

Other good candidates for a themed installation:

Sites managed by the same company, but with independent markets - like separate country sites for a brand

Multiple unique "microsites" for products managed by the same team (Individual books for a publisher, for instance)

Highly “designed” and customized landing pages

Architecture & Design Considerations

The reason your themed sites should share some similar content is that your Umbraco installation will contain all the Document Types needed to maintain each of the sites. Being able to use the same Document Types in various sites will keep the entire installation from becoming unwieldly.

Since the designs of each site will likely vary a great deal, you should design your Document Types according to content and data rather than page layout. Having structured content will give you a lot of precision when building out the site variations. For more free-form pages, use the Umbraco Grid control to handle design-specific content with maximum flexibility.

When creating your various site designs, here are two tips which will make the subsequent site implementations simpler:

Design with the content properties and grid in mind – Consider how the data you are already storing can be used in the design elements for various sites, and for less structured content, think about how the grid control can be used to provide specific design implementations – either by using multiple grid widgets to construct the design, or via custom macros.

Using front-end frameworks can be helpful – If you can standardize on using a certain front-end framework (such as Bootstrap, Responsive Bp, etc.) across the different site designs, you will be able to re-use portions of template or macro code, and the grid markup will be consistent.

The Theme Logic

The way that theming works in this arrangement is that Document Types have associated Templates as usual – with matching View files in the standard Umbraco “Views” folder.

When you create a new theme to use for a site, all the associated files are kept together in a single theme-named folder which contains two subfolders: “Assets” and “Views”.

The “Views” folder contains any View files that should override the default ones with the same name for the theme.

In practice, you can allow multiple Template choices for a Document Type, and whichever Template is selected for a given node will be used to render that specific node. Also, if you do not provide a themed version of a Template, the default View (from the main ‘Views” folder) will be used. (This is most useful for non-designed pages such as XML sitemaps.)

The routing to the themed View files is handled in a Default Controller which is simple to set up.

Setup & Components Needed

To set up your themed sites, there are a few standard components you will need. (Some of these items have been adapted from Shannon’s "Articulate" code.)

2. App_Plugins Theming

Technically, you could also move the “Themes” folder somewhere else in the site tree – as long as you update the path in the ThemeHelper.cs and ThemePropertyEditorApiController.cs files.

3. “Site Theme” Datatype and Property

Using the “ThemePropertyEditor”, create a datatype and add it to your “level 1” Document Type (something like “Site” or “Homepage”) with the property alias “SiteTheme”. This will allow you to select an available Theme folder at the site root for each site.

4. Update the Default Controller to use theming

This default controller code will replace the current template view with the themed version, if available, on page render. Use the “ApplicationStarting” event to set the Default Controller for the entire application.

5. Base Templates

As you create your Document Types, go ahead and create the Templates along with them in the standard fashion. Even if the related View files are essentially empty, having them present in the “~/Views” folder will prevent YSOD errors. When creating a theme, just create themed View files with the same names, but in your Theme’s “Views” folder.

6. Base Macros

You can create themed versions of macros as well. First, create the Macro via the back-office as usual, and update the code in the MacroPartial file to use the current site’s theme to render the associated theme file.

Then add a customized macro file in your “~/App_Plugins/Theming/Themes/MyTheme/Views/Partials/” folder with the name "Macro_ArticlesListing.cshtml"

7. Base Grid Editors + Updated Grid Rendering file

Similar to the other types of view files, you can create basic grid editor files (located at “~/Views/Partials/Grid/Editors/”), which will be used by default. With a small update to your grid rendering file, you can also create grid widget overrides in an equivalent Theme folder (“~/App_Plugins/Theming/Themes/MyTheme/Views/Partials/Grid/Editors/”).

Adding New Themed Sites to Your Installation

Once you have the basic components in place, you can begin adding themed sites. Create a folder for the new Theme and select it on the root site/home node for the new site, add you page nodes and customize the theme View files as needed.

For one-off design elements which don’t neatly fit your existing grid widgets or macros, you can use a “Code Snippet” widget to pass in straight HTML/JS or the path to a very customized partial view for rendering inside your grid. A bit of coding creativity will ensure all your needs are met.

You’ll find that individual site development can go pretty quickly once you have the basic Document Types and theming setup in your application. You can spend your time working on more elaborate front-end designs and interactions, or just putting together solid content.

Heather Floyd is a Senior Umbraco Developer at Scandia where she enjoys creating architecturally elegant Umbraco websites. She blogs occasionally at HeatherFloyd.com.

Scandia is a boutique web and app development agency that specializes in Umbraco for financial industries. Learn more at MyScandia.com.