I’ve just finished redesigning my site and implementing that design as an Orchard Theme. While it’s still fresh in my head I wanted to write down what I’d learnt. The documentation on the Orchard site is pretty good, but I wanted to write down the things that I found most important. I hope you find it useful.

An Orchard page is made of lots of bits; layout, zones, shapes, items, parts and fields. This can be a bit confusing and I’m still getting my head round it. You can find a more complete description of all of these in the anatomy of a theme in the Orchard documentation.

The HTML that displays all these bits is controlled by various CSHTML files and an XML file. If you’ve not used CSHTML before I’d recommend reading Scott Guthrie’s blog post Introducing Razor.

Even if you create a blank theme there are defaults for all the different parts of an Orchard Theme. The defaults are still controlled by CSHTML files, but they’re a bit scattered and hard to find at first if you don’t understand the rules. The defaults are quite sensible and you may find that you don’t need to override many of them and a lot of your styling can be done with your style sheet. I’m going to go through the files that I needed to override to create my theme.

First you need to generate your theme. You could copy an existing one, or use Orchard’s code generation feature. Now you’ve got a blank theme and can start having fun.

/Theme.txt

Here you can give your theme a nice name and a description. These are only really important if it’s a theme you’re going to share. The most important bit is where you define what zones you’re going to use. Zones are the parts of your page where you can place content and widgets. I thought I’d be able to choose my zone names but it seems you need to pick from the possible zone names defined by Orchard. These are: Header, Navigation, Featured, BeforeMain, AsideFirst, Messages, BeforeContent, Content, AfterContent, AsideSecond, AfterMain, TripelFirst, TripelSecond, TripelThird, FooterQuadFirst, FooterQuadSecond, FooterQuadThird, FooterQuadFourth and Footer.

/Views/Layout.cshtml

This is the main layout of your site and is used for all pages in your site. It covers everything between the opening and closing body tags. It’s where you get to control where on the page the various zones will be shown. You can even include conditional logic that will only show things if a zone has content in it.

/Styles/Site.css

You don’t need to call your style sheet Site.css, but it must go in the styles folder. You can register a style sheet at any point, but for a site wide style sheet you will probably want to do this in Layout.cshtml. You register a style sheet like this:

@{ Style.Include("Site.css"); }

/Views/Content.cshtml
/Views/Content.Summary.cshtml

These control the overall layout of a piece of content like a blog post or a page. The summary one controls how it looks when displayed as part of a list. I thought I would need to change these, but they actually delegate most of what they display to content part templates. The actual layout specified in the default was good enough for me so I stuck with it.

/Views/Content-11.cshtml

I wanted to display the content on my homepage slightly differently than other pages. My homepage has an ID of 11 so I was able to reference it with a file called Content-11.cshtml. I could also have created a template for all blog post content using a file called Content-BlogPost.cshtml had I needed to do so.

/Views/Parts.Common.Body.Summary.cshtml

I wanted to change how long the body text of a summary was and this is the file that controls that.

/Views/Parts.Common.Metadata.cshtml
/Views/Parts.Common.Metadata.Summary.cshtml

This shows the date a post or page was published. I wanted to change it to use the HTML5 time tag.

/Placement.info - The order of things

I wanted to display the tags and comment count under a post and this is where I got stuck. The templates defined several shapes that made up a piece of content like header and footer, but didn’t say what went in these. The templates for the tags and comment count just controlled how those looked and not where they were placed. This is where Placement.info steps in. Each module has its own placement file that defines where the parts like to live, but you can override this in your theme’s placement file.

My Placement.info file looks like this:

<Placement>
    <Match DisplayType="Detail">
        <Place Parts_Tags_ShowTags="Footer:1"/>
    </Match>
    <Match DisplayType="Summary">
        <Place Parts_Tags_ShowTags="Footer:4"/>
        <Place Parts_Comments_Count="Footer:5" />
    </Match>
</Placement>

What file is what and where can I find the base file

Figuring out theming for me was all about seeing a part of the page and figuring out which file I needed to copy into my theme to change it. Sometimes I needed to copy a file and then change its name so it was more specific to a particular type of content. I found the Experimental Developer plugin very useful. With this installed you can hover over a part of the page and it will tell you the file you need. It changes the page’s HTML though so I needed to turn it off when I was using Firebug to look at my pages makeup.

I couldn’t always find the file I needed using Experimental. I found the table of Template naming rules in the Orchard documentation very useful in these cases and more.

As the files are a bit scattered I found the search feature in Solution Navigator very useful. The Solution Navigator is part of the Productivity Power Tools extension for Visual Studio 2010 and is definitely worth installing if you haven’t already.

My blank theme

I've taken what I've learnt from this and created a simple blank 2 column theme. It includes some labels to help you work out which file controls what. You can download my Blank Theme from the Orchard Gallery. It's not as sophisticated as the Theme Machine, but it brings the common template files you'll need together. If there's anything else you'd like this theme to illustrate then please let me know.