All About Themes

A theme defines the look and feel of your Web Pages CMS site. The default installation of Web Pages CMS offers a theme that uses the popular Twitter Bootstrap front-end framework. 

Components of a theme

A theme exists as a folder within the Themes directory. The name of the theme is taken from the name of the folder. The default theme is in a folder called "Default". It has 3 subdirectories: Layouts, Styles and Zones.

Themes folders

Layouts

The Layouts folder contains a single file: _SiteLayout.cshtml. Files in the Layouts folder determine the structure of pages. The code for the _SiteLayout.cshtml file is as follows:

@inherits CmsWebPage
<!DOCTYPE html>
 
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    @RenderSection("Meta", false)
    <title>@Page.Title</title>
    <link href="~/Content/bootstrap.min.css" rel="stylesheet" media="screen">
    <link href="~/content/bootstrap-responsive.css" rel="stylesheet">
    <link href="@Themes.GetResourcePath("Styles", "default.css")" rel="stylesheet" media="screen" />
    <script src="~/Scripts/jquery-1.9.1.min.js" type="text/javascript"></script>
    <script src="~/Scripts/bootstrap.min.js" type="text/javascript"></script>
</head>
<body>
    <div id="top-bar">
        <div class="container">
            <header>
                <div id="head" class="row-fluid">
                    <div class="span12">
                        @RenderZone(1)
                    </div>
                </div>
            </header>
        </div>
    </div>    
 
    <div id="nav-container">
        <div class="container">
            <div class="row-fluid">
                <div class="span12">
                    @RenderZone(2)
                </div>
            </div>
        </div>
    </div>
 
    <div id="wrapper" class="container">
        <div class="row-fluid">
            <div id="col-main" class="span8">
                @RenderZone(3)
                @RenderBody()
                @RenderZone(4)
            </div>
            <div id="col-right" class="span4">@RenderZone(5)</div>
        </div>
    </div>
 
    <div id="foot" class="container">
        <footer>
            <div class="row-fluid">
                <div class="span12">
                    @RenderZone(6)
                </div>
            </div>
        </footer>
    </div>
    
    @RenderSection("Script", false)
    @RenderZone(7)
</body>
</html>

All layout files must include @inherits CmsWebPage as the first line. The bulk of the file contains HTML5 markup, but it also includes some inline Razor expressions. They are as follows:

RenderSection("Meta") and RenderSection("Script")
These calls to RenderSection are responsible for rendering out any Meta Tag information that you provide for a page. They both include false as the second argument to the RenderSection call, which states that neither section actually requires any content. If the calling page does not declare a section called Meta or Script, the site won't throw an error.

Page.Title
The title of the page is rendered via the Page.Title variable.

Themes.GetResourcePath
The Themes.GetResourcePath call picks up the current theme and resolves the correct folder based on its name. It is used to reference theme-specific files such as CSS files.

RenderZone
Zones are area within a layout where widgets can be placed. They are used to control the posiitoning of a widget. You can have as many zones as you need and can place them wherever you like. The default layout has a zone in the head, one in a navigation area just below the head and one on the left column. Then there are two within the main content area either side of the RenderBody call. It has one in the right column and one in the foot area. The final zone is placed just at the point before the closing body tag. This zone is intended for rendering analytics widgets and other Javascript that is not meant to result in the display of any UI.

RenderBody
RenderBody results in the content that you add when creating a page being displayed. You don't have to have any zones in your layout, but you must have a call to RenderBody, and you can only have one of them.

Styles

The Styles folder is where Cascading Style Sheets for the theme are stored. Whereas the name of the Layouts folder, and that for the Zones are important, you can actually name the style sheet folder anything you like. The only time you reference the styles folder in code is in the Themes.GetResourcePath call covered earlier, and you have to pass in the name of the folder when you do that.

Not all style sheets for the default theme are stored in the Styles folder. This is because both the Admin section of Web Pages CMS and the default theme make use of Bootstrap. The style sheets for Bootstrap are stored in the Content directory, which is not part of the Themes feature. 

Zones

The Zones folder contains XML files that provide definitions for the zones. Each file is named after its layout page. The name must be an exact match, including the leading underscore - although the file extension is different. The structure of the XML file is as follows:

<?xml version="1.0" encoding="utf-8" ?>
<layout>
    <name>default</name>
    <description>The default layout with header, footer and two columns</description>
    <zones>
        <zone>
            <id>1</id>
            <name>Header</name>
            <description>The head area</description>
        </zone>
    </zones>
</layout>

The file has a root element called layout. It has a name element which takes the name of the layout. You can provide a description of the layout if you wish. The document contains a collection of zone elements. Each one has an ID matching the number provided to the RenderZone method call in the corresponding layout file. Each zone must have a name. This is used in the Admin area to identify the zone in various dropdown lists. The description is optional.

Registering a Theme

If you prefer not to use the Bootstrap theme provided by Web Pages CMS, you have two choices. The first option available to you is to replace the contents of the Default theme directory with your own _SiteLayout.cshtml and _SiteLayout.xml files, This is the easiest approach in that there is nothing more to do. The theme will automatically be registered by Web Pages CMS.  Alternatively, you can create your own theme, name it something other than Default, and add it to the Themes directory alongside the Default theme folder. If you do this, you need to register your theme with Web Pages CMS as the new default theme. You do this in the _AppStart.cshtml file which is in the root of the web site. Look for the following line of code:

Themes.Initialize("~/Themes/", "Default");

Change "Default" to the name of your theme.