Clarity Systems Group, LLC
Software Engineering for Fun and Profit

Bytecode API
Group Tracker

Sitemask logo

Overview of Sitemask

Jason Sando, 26 June 2002


The look of a web site is defined by its theme — the choice of colors, the layout, and the presentation and operation of its menus (or "navbars").

If you've ever put together a full web site, you've probably knocked your head against the wall over the creation of the site theme. Creating and maintaining the theme is the most difficult aspect of web site administration. The tools and methods used in the production of web sites must facilitate regular changes to the theme.

There are many different techniques for reducing the workload of managing your web site's theme, ranging from manual editing through various attempts at automation.

If you use a simple text or HTML editor to create your site, you may have inserted the navbar and layout code into every page on your site, possibly modifying it slightly to show which menu option is selected. This is a silly way to maintain a site. What if the list of menu options, or the layout must be modified? You must manually change every page in the site!


Back in 1996 we though frames would solve all our problems! The layout and menus remain loaded in one side of a frame, while the document in the other part changes out. You can nest frames within frames and get arbitrarily complex layouts. You can even hide a frame and leave it loaded all the time, which is great for writing script-based web applications (for all those global variables ;)

A sample frames-based page, the Java API References.

Image 1: A page using frames.

The W3C added frames to the HTML 4.0 Specification, in December 1997 ... just as we all discovered they weren't really so great after all. Frames brought their own baggage — namely bookmark problems. If you try to bookmark a frame-based page you'll find that you either bookmarked the page contained inside the frame, without the menubar and theme, or you got just the top-level frame itself and not the specific page you wanted at all. Specifically, the use of frames leads to unpredictable bookmarks. Why are bookmarks important? Do you care if people come back to your web site once they've found it? Then bookmarks are important to you!

Another drawback with frames is that frame-based web pages don't look very nice. They tend to have scrollbars in the middle of the screen, or areas that you expect to scroll that inexplicably seem to stay still.

They still have a use, such as for reference manuals or other help text.(see Image 1 for a nice use of frames).

When most people encounter a site using frames, they assume it is an older site, or at least using old technology. This is probably not what you want your visitors to be thinking about you.

Server-Side Includes

Server-side includes (see Image 2) are another technique for merging the theme HTML into every page in a web site. This technique involves putting the theme code into separate files, and then including the contents of the theme file(s) at the right spot in each web page, while the page is being served up to a remote web browser.

A page using server-side includes.

Image 2: A page using server-side includes, for Apache.

An included footer theme file.

Image 3: An included footer theme file.

For example, you could use a server-side include to read in header and footer code from an external file and merge it with each document as it is requested. The header could define the menu bar, and a table that centers the main document body, while the footer closes the table and adds a nice copyright statement. Image 3 shows the file included by the bottom "include" tag from Image 2.

Using a server-side include has its drawbacks as well. The pages must be specially created with the server include tags. Also, the include is specific to a particular web server. Plus, the actual HTML pages do not show the complete code until served up. It also requires more work of the server for every request.

Content Management

You could opt for a Content Management System type of solution, such as Zope (see, where all the content is produced dynamically. To do this you must acquire, install, and learn how to use a new server, probably in addition to the web server you already use.

The performance will be less than with static pages, but unless you are you probably won't notice it. If you are willing to invest a lot of time, a Content Management System has many advantages over static files.

Microsoft, Macromedia, Etc.

Tools such as Dreamweaver and Fontpage offer some tools in support of themes, but getting them to work as you design can be difficult. Also, the HTML that such tools produce guarantees "lock-in", which is the vendor's way of sticking his tongue out at you and saying "nah nah nah, you're stuck with me!".

Keep It Simple

Suppose you want to keep things simple. You want static HTML pages, checked into your version control system (or not) as they will appear when deployed. No special tools needed to view a page, no "build" process needed to recreate a past version.

You need some kind of template or "theme" based tool that can enhance your existing web pages with your chosen theme, and extract it back out again when you decide to change it.


Sitemask is a tool for applying themes to web pages, including the generation of the menus.  It processes all the pages in a web site, first removing and then adding the theme to each page.  It marks the modifications it makes in each page, so they can be removed and updated later.  This is similar to the technique used by both Frontpage and DreamWeaver.

The following images illustrates the effect of Sitemask, showing both the before and after.  First, the original, un-themed html file is shown:

Pre-Sitemask html file.

Image 4: An un-themed HTML file.

The following image shows how this (rather boring) page looks in a web browser:

Pre-Sitemask html file (preview).

Image 5: The un-themed page in a web browser.

Next, after Sitemask has been run to add a nice theme. Notice the begin/end theme tags it has wrapped all the generated HTML in, so that it can extract the original page contents later:

Sitemask html page.

Image 6: The HTML file with theme added.

And finally, the newly themed page in a web browser. Looks a bit nicer than the original!

Sitemask html page preview.

Image 7: The themed page in a web browser.

You can see that Sitemask added quite a bit of code in Image 6 v.s. Image 4, to get Image 5 to look like Image 7.  The quantity and contents of the code added is irrelevant -- because it is marked as being part of the theme, Sitemask can remove it or replace it easily, at any time.  It is always easy to get back the original HTML page in this way.

But Where Did the Menu Come From?

You may have noticed a menu or "navbar" suddenly showed up in Image 7 (the tabstrip across the top), but the original HTML file didn't specify it.  The theme added it, of course, based on the contents of a special file: the site layout file.  The file is commonly named menu.txt and resides in the root directory of your site.  It contains a description of the menu choices and the links to which they point.  The file is processed by Sitemask into a Tree structure in memory, and passed to the theme to be used as each theme sees fit.

Here is a sample site layout file:

Sample site layout file (menu.txt).

Image 8: A sample site layout file.


Sitemask is a nice, simple tool for enhancing the pages within a web site with a theme.  It provides facilities for managing site navigation via a site layout file.  It is unobtrusive, and can be removed or updated at any time.  It gives you the power to manage your entire web site effectively, without locking you in.

Copyright 2004 Clarity Systems Group, LLC