The Siren Song of SSI

I needed to get a small content website up and running for a project a friend of mine and I are working on, and we started discussing what to use; i.e. raw HTML, a web framework, a CMS, or something else. I have experience on ASP, IIS, and Windows Server using my own mini ASP-based framework but I’ve got very little experience on our chosen deployment platform and hence am not productive on any of the common platforms in use on Linux. So my friend, thinking I was unfamiliar with SSI suggested that I just use SSI with HTML, to which I replied:

Oh, I’ve done that in the past; I built up a pretty robust set of SSI templates, but it took me a while to get the feel of the language and make it all work. So I don’t want to reinvent the wheel.

To which he replied:

But SSI is beautifully simple. You write a couple lines for your header, say, then throw it in a file. Then you write a page containing whatever content you want, with a call to include that header file at the top of the document. Then…well, that’s it. It takes no time to "learn", requires no programming, and seems perfectly sufficient for what you want.

Sigh.

But as I was thinking about how to reply, I realized that my reply would make an interesting blog post. So here it is; I’m going to build a simple website and use SSI to eliminate all the inevitable duplication. Let’s see how it goes.

First thing is to create a header and a footer (please forgive the lack of DOCTYPE and of obvious things we’d add as I’m trying to make my examples easy to follow. And the omission of DOCTYPE and other specifics won’t affect my main points anyway):

header.inc:

<html><body>

footer.inc:

</body></html>

Next step is to create a template for all our web pages; we’ll start by creating the home page:

index.html:

<!-- include virtual="/header.inc" -->
The web page's HTML content would go here
<!-- include virtual="/footer.inc" -->

So far, so good. Next let’s add a menu to header.inc that will be on all pages in the website. We’ll need to use CSS styling for the menu, so we’ll add a LINK element allowing us to bring in CSS:

header.inc:

<html>
<head>
<link rel="stylesheet" type="text/css" href="/style.css" mce_href="/style.css">
<body>
<ul id="menu">
<li><a href-"/">Home</a></li><li><a href-"/products/">Products</a></li>
<li><a href-"/downloads/">Downloads</a></li>
<li><a href-"/store/">Purchase</a></li>
<li><a href-"/faq/">FAQ</a></li>
<li><a href-"/about/">About</a></li>
<li><a href-"/contact/">Contact Us</a></li>
<ul>

Great! Now let’s start building out our website. Let’s add three, five, ten, twenty five web pages, and more. These SSI are pretty nice, no?

But wait. Someone mentions to us that none of our web pages have titles. Bummer; titles are really important for usability, and super important for search engine optimization. Oops.

So how are we going to fix this? Hmm, looks like we need to split header.inc into two parts and add a <title> element spanning the two.

header1.inc:

<html>
<head>
<link rel="stylesheet" type="text/css" href="/style.css" mce_href="/style.css">
<title>

header2.inc:

</title>  
<body>
<ul id="menu">
<li><a href-"/">Home</a></li>
<li><a href-"/products/">Products</a></li>
<li><a href-"/downloads/">Downloads</a></li>
<li><a href-"/store/">Purchase</a></li>
<li><a href-"/faq/">FAQ</a></li>
<li><a href-"/about/">About</a></li>
<li><a href-"/contact/">Contact Us</a></li>
<ul>

Well that’s done, but now we need to go and fixup all those three, five, ten, or twenty five odd web pages, right? I guess it’s going to look something like this:

<!-- include virtual="/header1.inc" -->
Page title goes here
<!-- include virtual="/header2.inc" -->
The web page's HTML content would go here
<!-- include virtual="/footer.inc" -->

I guess that wasn’t too bad. But wait. It becomes clear some of our pages need to omit the menu. Hmm. I guess we need to split the menu out of header2.inc and into it’s own file.

header2.inc:

</title>  
<body>

menu.inc:

<ul id="menu">
<li><a href-"/">Home</a></li>
<li><a href-"/products/">Products</a></li>
<li><a href-"/downloads/">Downloads</a></li>
<li><a href-"/store/">Purchase</a></li>
<li><a href-"/faq/">FAQ</a></li>
<li><a href-"/about/">About</a></li>
<li><a href-"/contact/">Contact Us</a></li>
<ul>

I guess that means NOW we need to revisit those three, five, ten, or twenty five odd web pages AGAIN, right? They should probably all look something like this:

<!-- include virtual="/header1.inc" -->
Page title goes here
<!-- include virtual="/header2.inc" -->
<!-- include virtual="/menu.inc" -->
The web page's HTML content would go here
<!-- include virtual="/footer.inc" -->

Sheesh! What’s with this SSI concept? I thought it was suppose to eliminate the need to change every web page file every time we needed to modify a site’s architecture. Why then do we have to keep making all these sweeping changes?

What’s more, those web pages are really hard to read, what with all the cryptic SSI syntax obscuring the logic in the page.

So I’ve shown two simple examples of where a web site rearchitecture requires refactoring of (almost) all of the web pages in a site when SSI is used naively. Yet I could go on. And on. And on. And on. The problem is that you can’t easily parameterize SSI files (easily) and then capture those parameters in pure HTML. And even if you could, you’d be programming, and you’d have to learn how to do it! We’re going full circle, you know?

Which brings me to a question: "Are Server-Side Includes Bad?" And the answer is: "Of course not, but you do need to know how to use Server-Side Includes properly, and they are really only beneficial when paired with a server-side scripting language[1]." I’ve actually used SSI on every web project I’ve every worked on, save the very first. But I have a rule of thumb when using SSI: I generally only use one SSI per web page file, and I include that SSI at the top of the web page file. My single include file actually includes my library of scripting functions and is a mini-framework of sorts.

So that you can see a good way to use SSI, I’ll show a quick example. The majority of my web experience has been on programming ASP websites so I’ll use ASP and VBScript syntax. For those not familiar, ASP/VBScript is relatively similar to programming in PHP albeit PHP has moved far beyond the capabilities of ASP since Microsoft dropped ASP and went on to focus its efforts on that that abomination they call ASP.NET[2].

default.asp:

<% 
   '--Filname: /default.asp 
%>
<!-- include virtual="/sitedef.inc" -->
<%

With page
   .Title= "Page title goes here"
   .Show()
End With

Sub PageContent
%>
The web page's HTML content would go here
<%
End Sub
%>

For completion, I’ll so a tiny subset of a workable sitedef.inc as showing and explaining the entire thing would be way out of scope for this article:

sitedef.inc:

<% 
   '--Filname: /sitedef.inc 
   Option Explicit
%>
<!-- include virtual="/funclib1.inc" -->
<!-- include virtual="/funclib2.inc" -->
<!-- include virtual="/funclib3.inc" -->
<!-- include virtual="/and-so-on.inc" -->
<%
Dim pageSet page= New PageClass
Class PageClass
   ...
End Class
%>

A quick rundown of sitedef.inc shows the first line being a comment to document the file name for print-outs, etc.. Next is the directive Option Explicit that turns on error reporting for undeclared variables.

Then you can see several times the use of embedded SSI to bring in other files from my VBScript library of functionality. As a note, at first I thought that incluing everything even if it wasn’t needed would cause poor performance but I later realized everything was cached and there really were no performance problems at all. At least this is true on ASP and IIS; I can’t yet speak for PHP or other languages on Linux and Apache.

Then we have the declaration of the "page" variable which you saw used in default.asp above, the creation of a new instance of the page variable, and the skeleton declaration of the "PageClass" class. Note that VBScript is case insensitive and won’t let you reuse symbols so the "page" variable and a class named just "Page" would have clashed hence the use of the suffix "Class" on "PageClass."

With sitedef.inc we can now create our three, five, ten, twenty five, or more web pages using the template shown for default.asp and (almost) never have to modify them when we refactor the code in our server-side includes. Much more maintainable than SSI and HTML alone. Which brings me back to my friend’s statement, a portion of which I repeat below:

But it takes no time to "learn", requires no programming, and seems perfectly sufficient for what you want.

If you are going to use SSI and you want it to be maintainable, it actually does require you learn server-side programming. Maybe we are only talking about three or five web pages for the project today, but we all know that things change quickly and before you know it, there will be fifty web pages or more.

And who wants to architect a website such that you have to rearchitecture as soon as it grows? Not me. :)

Footnotes

When I say server-side scripting I’m using the term "scripting" liberally to refer to any server-side programming solution including platforms that use Java and C#.
Please don’t misquote me; it’s not the .NET framework, .NET languages, and the common language runtime I dislike; it’s the ASP.NET web framework that I think is misguided.

header.inc:

footer.inc:

index.html:

header.inc:

header1.inc:

header2.inc:

header2.inc:

menu.inc:

default.asp:

sitedef.inc:

Footnotes

One Reply to “The Siren Song of SSI”

Leave a Reply Cancel reply