yurt: a content management system

Designing a Yurt CMS Site

The Yurt CMS is a content management system in the 'pure' sense of the word. The job of the system is only to manage the organization, generation and maintenance of content. The mechanism for displaying the pages is completely divorced from the system, allowing you to deploy a working site without having to worry if the destination server supports the Yurt CMS.

The presentation and templating of the site is handled with SSI's. To see how this all fits together, let's start off with a bird's eye view of the htdocs/ directory right after running yurt newsite:

index.html
media/
    css/
        styles.css
    images/
        admin_bg.gif
        admin_head.jpg
        directory.png
        file.png
        pane_bg.gif
    js/
        prototype.js
includes/
    content/
        index.html
        index.metatags.html
    template.html
    template.metatags.html

The media/ directory is a convenience feature, with images, javascripts and css directories included, as almost all sites use these directories. With that out of the way, let's see how the index.html page is created. Opening it up, we get:

<!--#set var="PAGE" value="./index" -->
<!--#include virtual="/includes/template.html" -->

Not much to say, since there's not much there. We're setting a variable called $PAGE and calling the template.html file. Obviously the heavy lifting isn't being done here. Let's open up the template.html file:

<!--#include virtual="/includes/template.metatags.html" -->
<!--#include virtual="/includes/content/${PAGE}.metatags.html" -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title><!--#echo var="TITLE" --></title>
        <meta name="keywords" content="<!--#echo var="KEYWORDS" -->" />
        <meta name="description" content="<!--#echo var="DESCRIPTION" -->" />
        <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    </head>
    <body>
        <div id="main">
            <!--#include virtual="/includes/content/${PAGE}.html" -->
        </div>
    </body>
</html>

Ah... much more interesting. The first two lines are basic includes, and we're pulling in the metadata that will be used for the page. The second line is interesting because we're using $PAGE to pull in page-specific metadata. The metadata ends up being used in the <head /> section of the page.

Going down into the <body /> area, we find the place where the actual page content is being included. The layout is very simply put together, but this can be extended in powerful ways.

Notice that all web site content and metadata are stored inside the includes/content/ directory. The contents and structure of this directory will, in fact, mirror the content and structure of the htdocs/ directory and the source content/ directory. It is this mirroring allows us to easily set up the convention of defining a $PAGE variable the way we do.

The template.html file is the touchstone for determining the look of your site. When it's time to take an approved mockup and turn it into production HTML code, the result of your work must be incorporated into this page somehow. The trick is to decide what parts of the page should go into the template, and what parts should be managed with the Yurt CMS. Surprisingly, you could put a lot of stuff into the CMS.

This site itself was built using the Yurt CMS. Let's look at the changes I made to the template to make it work for this design:

<body>
 <img src="/yurt/media/images/admin_head.jpg" width="481" height="79" border="0" alt="yurt: a content management system" id="header_img" />

 <div id="main">
   <!--#include virtual="/includes/content/${PAGE}.html" -->
   <div id="footer">
     <!--#include virtual="/includes/content/footer.html" -->
   </div>
 </div>
 <div id="menu">
   <!--#include virtual="/includes/content/main_menu.html" -->
 </div>
</body>

The rest of the template is identical to the default template file. As you can see here, I've added a few bits -- a <div /> tag for the footer, and another for the menu, with their associated include tags. You'll also notice that the path to the footer and menu are hard coded.

What's happening here is that I'm exploiting another feature in the Yurt CMS, which is the notion that there are two types of content that you can add to the site. The obvious first type is the notion of the page. The page includes metadata like title, a description, and keywords to be used in the meta tags. However, there are going to be times when we want to include content like a menu, or a footer, which doesn't have that metadata. So, when adding new pages, you have the option of creating a 'partial', which omits the metadata.

A file that is a partial also has an impact on what files are generated -- or rather, which files aren't generated. Generating a partial does not generate a file in the htdocs/ directory. It doesn't generate a metatags.html file either. I could have pretended that this distinction between page and partial was unimportant, and allow those files to be generated, which might be interesting if you wanted to allow the partial content to be viewable on their own, but I felt that 80% of the time, the extra files that could have been generated would only have served to clutter up the content.

Working With Multiple Templates

At this point, and probably well before, you may be wondering how to set up sites with multiple templates. In the abstract, all you need to do is create multiple template files that look like the ones above, modulo your changes. The important thing to remember is that you need to save your new templates in the /includes directory, and the end of each template file must end with template.html. The other thing to keep in mind is that if you want to set a default template file, that file must be called template.html.

When working with files from the Web UI, the Yurt CMS first checks for any and all files that end with template.html, and creates a drop-down list of matches. If the CMS is creating a new file, or editing a file that has no template configuration, it defaults to template.html.

Let's work through an example. Suppose you're planning to build a site that needs two templates, one for the homepage, and one for the rest of the site. Since there's only one homepage, You decide to name it homepage-template.html and save it to the includes/ directory. The default template becomes template.html.

If you're working in the Web UI, open up the page that you want to use the new template. When you check out the dropdown, you'll see homepage-template.html as one of the options in the list. Select it, and save the file. This will generate the file with the new template.

If you're working from the console, then simply add a new line (if it's not already there) that looks like the following:

template: homepage-template.html

Other Templating Tricks

Creating alternative templates can open up some interesting possibilities. Suppose, for example, that you maintain a set of news releases in this site, and you would like to take the list of headlines found in news/index.html and re-use it on the homepage. Since you've already created the homepage-template.html file, all you need to do is include a line like this:

<!--#include virtual="/includes/content/news/index.html" -->

in the template, and only pages that use the homepage template would see the news. In fact, if the layout of the news on the news page isn't identical to how you'd like it shown on the homepage, there's nothing to prevent you from editing homepage-template.html to point to an alternative CSS file that restyles that content to suit.