SSI (Server Side Includes)

What is SSI?

SSI stands for Server Side Include. Server Side Includes allow you to embed tags in your webpage that the server will then replace with the information you requested. The tag could tell the server to include an environment variable (such as the current date or time, or the date the document was last updated), insert some HTML or text from another file or even run a CGI script and insert the results in the page.

Why might I find SSI useful?

You could use SSI to add a standard header or footer to all of your pages, create easily updated templates for web pages, automatically show the current date or time, or if you have a CGI script that you'd like to embed in one of your web pages all of this can be done using SSI. This can make your pages seem more responsive and up to date and even make maintaining your site easier.

Why should I use SSI when I can do much of this using Javascript?

While it is true that you can insert many simple properties like the current date and time into a page using JavaScript, and it is even possible to use JavaScript includes to create simple page templates there are disadvantages to relying on the surfer's web browser to do all of this rather than using your server.

The main problem with using JavaScript comes from the fact that it relies on the visitor's web browser, it's version and it's settings. Although the main web browsers are all capable of running JavaScript these days they have all implemented slightly different versions of JavaScript or ECMAScript in slightly different ways, which may be slightly incompatible with each other. You may find that the visitor has actually disabled JavaScript in their browser for security reasons, or simply because they are using a slow PC. It's also possible that a visitor may be visiting your site using an older browser or one that doesn't support JavaScript at all such as Lynx, or a browser running on a limited device such as a Palm Pilot or a WebTV device.

You will have none of these compatibility problems using SSI. As it is all run on the server itself and doesn't rely on the visitor's web browser at all these problems just disappear.

What do I need before I can use SSI?

The first thing that you need is a host that supports SSI, unfortunately most free and cheap hosts (including Geocities, Tripod and Angelfire) do not support SSI. If your host allows CGI scripts then they probably also support SSI but if in doubt check their FAQs or contact them directly, unfortunately you may find that some hosts will charge extra for SSI support.

Many hosts also require you to rename any pages using SSI to have a filename ending with ".shtml" rather than ".html" or ".htm", check your hosts FAQs for this, or any other requirements they may have.

You'll notice that this page, and many other pages on this site are named with a .shtml extension as I use SSI extensively across this site. The menu that you should be able to see to the right is added via an SSI command as are other elements of this page.

How does SSI work?

SSI is a bit like using your server to copy and paste bits of documents together to create a web page. When the visitor requests a web page from the server the following steps will happen:

  1. The server looks at the document's extension to decide whether this is a static HTML document and can be sent straight to the browser without any modification (.htm or .html), or if it may contain SSI commands and will require extra processing (.shtml).
  2. The server then reads through the document word by word looking for any SSI tags.
  3. When it finds an SSI tag it will attempt to run the command.
  4. It will then either insert the results of each command, or an error message if there were problems, and merge it all into one document.
  5. This merged document is then sent to the visitor's web browser.

Are there disadvantages to using SSI?

Unfortunately there is one slight downside to using SSI rather than having a plain, static HTML document and that is speed. With a normal static web page all that the server does when it receives a request is read the file from the disk and then send it straight out to the requesting browser, however with an SSI document the server has to read through the document and run extra commands to insert the required information. Unfortunately each of these extra steps does take a little extra time and the difference may be noticable if you have a slow or overloaded server, or if you are using SSI to insert some very complex scripts.

Most people find that the productivity gains, including ease of updating multiple pages, and advanced features allowed by SSI far outweigh any slight decrease in page loading speed.

What does an SSI tag look like?

SSI tags look a bit like a normal HTML comment tag, but with a couple of differences. Here's an example of an SSI command:

<!--#include file="bottom.inc"-->

Looking at the example above, we can see that the command starts with something similar to the normal HTML comment starting tag "<!--" which is immediately followed by a hash sign "#" to create "<--#". This is then followed by an SSI command "include" (see below for what this command actually does) and then an argument and it's value "file="bottom.inc"" and finally the closing part of the tag, which is just the same as a comment tag's end "-->". So a generalised SSI command looks like:

<!--#command arg1="value1" arg2="value2" ... -->

What SSI commands can I use?

Unfortunately there is no set standard for SSI commands that all server vendors adhere to. What this means that there are a core few commands that will work on most servers, and a number of additional commands that will only work on certain brands of server. You should check your hosts FAQs or check the documentation for your server (see below) for an absolute list of commands that will work for you.

Most SSI commands used are those invented and set on either the NCSA HTTPd or Apache web servers, some of the most common ones are listed below.

Include

The most basic SSI command that should work on any server that supports SSI is the include command. This is used to insert another document such as a text file or another HTML file in your document. You can use this command if you have a piece of text or HTML that will be used on many of your pages, such as a site menu bar, or a standard page footer. You can even use a more than one include commands on a page to create a standard template that would be the same for many pages.

The included file should be in plain text format and can have HTML tags within it if you want, but it shouldn't have be a full HTML page with headers and footers. It can have any extension to the file name but it is normal to either give it an extension that indicates that it is just an include file such as ".inc" or to give it either a ".txt" or ".html" extension depending on whether or not it has any HTML formatted text within it.

So to include the contents of a file in the current directory called "file.inc" in the current document you would use:

<!--#include file="file.inc"-->

If you'd like to include the contents of a file that is within your webspace on the server but in a different directory from the current document you would replace the "file" argument with a "virtual" argument. So to include the contents of a file called "disclaimer.txt" which is in a directory called "includes" in the current document you would use:

<!--#include virtual="/includes/disclaimer.txt"-->

For example, if you have a web page that looks like the following, where the list of links is your site's menu which you are duplicating on each page:

<HTML>
<HEAD>
<TITLE>This is the title</TITLE>
</HEAD>
<BODY>
<H1>Heading<H1>
<P><A HREF="home.html">home</A> <A HREF="about.html">about</A> <A HREF="page1.html">page 1</A></P>
<P>Lots of text goes here. Lots of text goes here</P>

...

</BODY>
</HTML>

Whenever you add another page to your web site (such as "page 2") then you will need to go through every page adding these link in unless you take out the menu and put that in an include file. So you could create an include file called "menu.inc", and add a reference to that to each page like so:

home.shtml

<HTML>
<HEAD>
<TITLE>This is the home page</TITLE>
</HEAD>
<BODY>
<H1>Home<H1>
<!--#include file="menu.inc"-->
<P>Welcome to my home page, please click on the links above to navigate around this site.</P>
</BODY>
</HTML>

Note that the HTML pages all been renamed to have the ".shtml" extension now.

menu.inc

<P><A HREF="home.shtml">home</A> <A HREF="about.shtml">about</A> <A HREF="page1.shtml">page 1</A></P>

Now whenever a surfer goes to your "home.shtml" page the "menu.inc" file will be magically inserted to provide them with a navigation menu in the correct position. The advantage of this is that every time you add a new page to the site and need to add it to the menu, you only need to update the "menu.inc" file rather than individually editing each HTML document one by one.

Echo

The echo command prints the contents of one of the server's environment variables to the document. An environment variable is a piece of information that the web server knows and can be provided to any program running on the server, some of these variables may change from one moment to another, whilst some may remain static.

An environment variable could be something like the current filename, the date it was last modified, the current date and time, details about the visitor's web browser or their address.

One example of an echo command:

<!--#echo var="DATE_GMT"-->

Some example echo commands and their results:

<!--#echo var="DATE_LOCAL"-->
The DATE_LOCAL variable contains the date and time according to the web server.
Result:
<!--#echo var="DATE_GMT"-->
The DATE_LOCAL variable contains the date and time according to the web server, this will make an allowances for the server's time zone and return the result in GMT, or Universal Time format.
Result:
<!--#echo var="SERVER_SOFTWARE"-->
The SERVER_SOFTWARE variable contains the name of the web server software running on the server.
Result:
<!--#echo var="SERVER_NAME"-->
The SERVER_NAME variable contains the web server's name.
Result:
<!--#echo var="DOCUMENT_URI"-->
The DOCUMENT_URI variable contains the current document's path, or URI.
Result:
<!--#echo var="HTTP_USER_AGENT"-->
The HTTP_USER_AGENT variable contains the full name of the visitor's web browser, including version number and any other relevant information that it may be giving out.
Result:
<!--#echo var="HTTP_REFERER"-->
The HTTP_REFERER variable contains the full URL of the page that referred the visitor to the current page (usually by clicking a link on that page).
Result:
<!--#echo var="REMOTE_HOST"-->
The REMOTE_HOST variable contains the IP host name of the visitor's computer.
Result:
<!--#echo var="REMOTE_ADDR"-->
The REMOTE_ADDR variable contains the IP address of the visitor's computer.
Result:

The above is only a selection of possible environment variables, you may find that your server may support some or all of the above and may have even more variables that you can use. Please check with your host, or look at your server's documentation to see which variables you have available.

Exec

The exec command is used to tell your server to run (or execute) a script, and then merge the results of that script into the web page. The exec command looks like:

<!--#exec cgi="/cgi-bin/cgi-program.pl"-->

The code above tells the server to run the program located in its "/cgi-bin" called "cgi-program.pl", and once that program has finished running to insert its result into the page at this point.

Useful Links

You may find some of the following links helpful:

Server Documentation