A WebQuarters template is just a normal HTML file, but with a few small changes.  In the hope that these will make sense, here is a quick overview of what's going on inside.  If you don't care about the inner workings of why and how, please feel free to skip to the next section.

Architecture Overview

WebQuarters uses MVC Areas, as prototyped by Phil Haack.  This means that CMS requests can be separated from any existing MVC application you might have or want to have alongside.  WebQuarters reserves only the areas "site" and "cms", meaning that the real homepage of the CMS-powered part of your site will be /site/.

The default behaviour is that the RootController (that is, the Controller for requests to the web root which you can find in /Areas/Root/HomeController.cs) redirects to /site/ - you can change this at any time and add your own logic as you would for a normal MVC controller.

To this end, when any request starting with /site/ comes in it gets sent to the Site area's HomeController class, which finds out what the underlying CMSPage object should be, based on the requested URL.  The required page then becomes CMSPage.Current, which is used by the relevant view (/Areas/Site/Views/Home/Index.aspx) to render out meta tags, required JavaScript, CSS references and such.

It also calls Html.RenderPartial to get the specified template for the current page, which is then simply rendered as a ViewUserControl.  As an aside, the Home view also utilises Site.Master (in /Areas/Site/Views/Shared/), which does very little other than set up the doctype.

Just incase none of the above makes any sense, here is a quick overview of which files are responsible for which parts of a WebQuarters site's pages:

1. DOCTYPE, HTML, HEAD and BODY setup - /Areas/Site/Views/Shared/Site.Master
2. HEAD contents - /Areas/Site/Views/Home/Index.aspx
3. BODY contents - /Areas/Site/Views/Templates/YOUR_TEMPLATE.aspx
   

How to implement your own templates

A template is essentially an MVC ViewUserControl, whose Model type is CMSPageVersion (that is, the revision of the requested page that should be shown to the user).  All templates start off with the Page declaration as follows:

<%@ Page Inherits="OpenQuarters.WebQuarters.Core.Web.Areas.Site.Views.Shared.TemplateBase" %>

The rest of the WebQuarters template is simply whatever is in the BODY tag of your HTML template.  This means that, on a basic level, the steps involved to implement existing markup would be:

1. Take any required CSS, JavaScript and images, and put them in the relevant folders of your WebQuarters project.
2. Modify the /Areas/Site/Views/Home/Index.aspx file to add any CSS or script references you require.
3. Create a new template (or modify an existing one) in the /Areas/Site/Views/Templates/ directory, and paste in the contents from the BODY tag of your HTML.

You should now be able to select this template for a page by logging into the site as an administrator and selecting the Page Information option in the toolbar.  In the Template drop-down, select your new template and save the changes.

Here comes the CMS bit

What you should have now is some static templates, but that's not going to cut it - this is a CMS after all!  Content exists in a WebQuarters page by taking the form of modules.

A module can take any form you'd like, and you'll find that a number of them come packaged in with the vanilla site.  We've tried to keep these to a minimum as to avoid over-complication of the system for end users, and the ones that are there exist because we think you'll need them in the majority of sites you build.

For example: the Page Content module provides HTML creation in a WYSIWYG format; the Navigation module provides an extensible menu system for your site; the Item List module provides a base for list-based modules such as news areas, blogs and event calendars.

Modules, being the atomic unit of functionality for a web page, need something to sit inside.  Nobody wants ends users sticking modules any old place they feel (especially not into your beautiful designs!), so we need to define the DIVs in your markup within which they are welcome to create new content.

To this end, pages contain content areas, and content areas contain modules.  So, to the final piece of the puzzle - how to change a regular DIV in your template into a CMS-able content area?



Just like that.  Your content area DIV must have an ID, but this can be any ID of your choosing, so long as it is unique on the page.  It must also be given the runat="server" attribute so that the WebQuarters innards can find it and fill it with the correct modules as it flies out to the browser.  Finally, give it the class contentArea so that the editor script (running on jQuery) can find it and make it editable to the site administrator.  You can give your div any other classes you want at the same time, but you must include contentArea.

Try it out!  Reload the page you're using the template on, and hover over the DIV with your mouse - you should get a bar showing you that the area can have modules added to it.  You may need to add some temporary content to the area in the template so that your browser renders it enough that you can get your mouse pointer in it, but a   should suffice for this purpose.

...and we're done.  For anyone who is still awake, please join us in the next post for interesting things you can do with content areas!