Server side includes (SSI) tutorial

Sean McManus explains how to use serverside includes to make your website easier to maintain and enable a few neat webdesign tricks, including adding a stylesheets switch to your website and inserting pseudo-random code snippets in your webpages.

While updating content-rich websites keeps them fresh and lively, it does the exact opposite for webmasters. What began as a few HTML pages soon becomes draining to maintain and update. But luckily there are technologies to make this easier.

Server side includes (SSI) is one such technology. It enables you to insert simple commands into your HTML pages, which the server will carry out before sending out the page to the reader.

The most useful of these commands enables you to insert the contents of a file into your webpage. You can use it to split your navigation bar and page header away from your content pages. When you need to add a new link to the navbar, or change the branding in your header, you only need to change the file that's being inserted and don't need to tamper with every HTML page which displays it.

Files that include SSI commands typically have the extension .shtml and files to be inserted are typically formatted as text files. But you can insert shtml files into other shtml files to have SSI commands obeyed in the file that's being inserted too. Be careful not to slow the server to a near-halt or set up a loop though.

SSI can also be used to show the last modified date of the current page or linked pages, as well as the file size of any downloads. The moment you FTP new files to your server, your visitors will see updated information.

Simple conditional statements enable you to display different messages for each day of the week or for users of different browsers. The server only sends out what the visitor needs, so if you have a message of 300 words for each day of the week, your visitor will only be sent the 300 words that apply today and not the 2100 words you upload in your shtml file.

We'll also see how you can add a simple stylesheet switch to pages. Just add links to the current page with different stylesheet names in the query string (eg link to index.shtml?coolblue or index.shtml?purplehaze) and let SSI do the rest.

To use serverside includes, you'll need to have a hosting package that supports them. If you're not sure, check with your host. In most cases, you'll be able to skip stage 1 below, because the host will have done it for you.

Stage 1

Configure the server to recognise SHTML files

Step 1

Configure the server
Chances are your server is already configured to recognise that it needs to parse SHTML files for SSI statements. If not, create a file in a text editor called .htaccess (dot htaccess) and include the line 'AddType text/x-server-parsed-html .shtml'. In Windows, it's easier to make a file called htaccess.txt and rename it on the server later.

Step 2

Parse existing files
If you want to use server side includes throughout your site (for example to add the same header to every page), you'll be forced to rename all your pages which will break the incoming links. To avoid that, you can configure your server to parse your existing .html or .htm files for SSI commands by changing the extension given in the AddType statement above.

Step 3

Upload the htaccess file
FTP the htaccess file to the top level of your website's directory structure. Rename the file to .htaccess if necessary.

Stage 2

Start using basic server side includes on your webpages

Step 4

Separate your navigation

<!--#include virtual="../header.txt" -->
<!--#include file="sidebar.txt" -->

Split your header into a file called header.txt and your navbar into a file called sidebar.txt. Use the include statements above where you'd like the files pasted in your webpages. Use #include virtual to reference files in a higher folder and #include file for those in the current folder or below. Now you can just edit sidebar.txt to update your navbar on all the pages it appears on.

Step 5

Date stamp your pages

This page was last updated <!--#echo var="last_modified" -->

By adding the above line to your SHTML file, you can make the server insert the time and date your file was last amended. When you update your webpages, the 'last updated' message will be automatically revised. That code in action:
This page was last updated Wednesday, 05-Jun-2019 14:25:42 CEST

Step 6

Provide modification dates for other pages

<a href="index.shtm">Home
(updated <!--#flastmod virtual="index.shtm" -->)

You can use #flastmod to display the modification date for other files. You can combine this with a link, as shown above, so that your visitors can see from your sitemap or navbar when each linked page was last updated. It looks like this:
Home (updated Sunday, 17-Oct-2021 11:00:17 CEST)

Step 7

Tidy up the date
The default date format is long and ugly. You can change it to be like 6/08/04 using the line <!--#config timefmt="%d/%m/%y" --> or can change it to resemble Friday 6 August 2004 using the line <!--#config timefmt="%A %d %B %Y" -->. The letter after the % sign represents a different part of the date or time in a particular format. There's a full list at www.oreilly.com/openbook/cgi/ch05_08.html.

Stage 3

Lesser seen SSI techniques

Step 8

Provide filesizes

<a href="latestsong.mp3">My latest song (<!--#fsize file="latestsong.mp3" -->)</a>

As well as telling people when files were last updated, you can display the filesize using #fsize. The example above enhances a simple link to latestsong.mp3 by automatically inserting its filesize in brackets. It's particularly useful where files are being frequently updated.

Step 9

Pseudo-random code

<!--#config timefmt='%S' -->
<!--#if expr='${DATE_LOCAL} >= 58' -->
<A HREF="url.htm">Link text</A>
<!--#elif expr='${DATE_LOCAL} >= 56' -->
<A HREF="url.htm">Link text</A>

...

<!--#elif expr='${DATE_LOCAL} >= 4' -->
<a href="url.htm">Link text</a>
<!--#elif expr='${DATE_LOCAL} >= 2' -->
<a href="url.htm">Link text</a>
<!--#else -->
<a href="url.htm">Link text</a>
<!--#endif -->

SSI is a basic technology and doesn't have support for random number generation. You can fudge it though, as long as you don't want a number greater than 60. The code above looks at the seconds part of the current time. It inserts one of 30 HTML code snippets based on the seconds counter.

Visitors arriving at the site two seconds apart will see a different message. Visitors returning to the page who don't have it cached will also see a new message unless coincidentally they're seeing the page at the same number of seconds into the minute.

It doesn't matter that my source HTML file is fairly long because of all these conditional statements. The server strips out the SSI commands and replaces them with what the end user needs. Although there are 30 'random picks' in my HTML file, the server only sends out the one the visitor should see now. This is one advantage over using Javascript to achieve a similar effect - the other is that SSI doesn't impose any requirements on the visitor's browser.

Step 10

Detect browsers

<!--#if expr="$http_user_agent = /MSIE/" -->
You're using Internet Explorer, so you should be able to use our plug-in just fine
<!--#else -->
Our plug-in only works on Internet Explorer: sorry!
<!--#endif -->

You can also use SSI to display different messages to different browser users. The message above will display one message for IE users and another for everyone else. It's a good way to warn people if they might have problems accessing your site without IE.

Step 11

Create a back button

<a href="<!--#echo var="http_referer"-->">Back</a>

Want to create a back button that will take people to the previous page without using Javascript? The code above will insert the URL of the previous page (the http referer) into a link tag. Here's that code in action:
Back

Step 12

Create a stylesheet switch

<!--#set var="chosenstyle" value="$QUERY_STRING" -->
<link rel="stylesheet" href="<!--#echo var="chosenstyle"-->.css" type="text/css">

In a URL like index.shtml?test, the bit after the question mark is called the query string. The code above takes the query string, adds '.css' to it and uses it as the style sheet filename. To use the stylesheet coolblue.css, for example, we visit index.shtml?coolblue. The example below shows how you can use SSI to insert the current query string at the end of links, so the user's choice persists between different pages of your site.

<a href="page2.shtml?<!--#echo var="chosenstyle"-->">Next page, same query string</a>