Don't worry, SSI doesn't require a rocket-science degree to understand and use. It is, however, a highly useful feature that lets you do incredibly time saving tasks such as include the contents of an external file across multiple pages on your site, or access and display server specific information such as the current server time, visitor's IP address, etc. In this tutorial I'll introduce new comers to the wonderful world of SSI! SSI is short for Server Side Includes, by the way.

Does my server support SSI?

The first thing that needs to be settled is whether your server supports SSI and have it enabled. SSI is a Linux/Apache specific feature, so if you're on a Windows server for example, you'll need to look for the Windows equivalent of SSI (sorry, not a Window's guy). To test if your server supports SSI then, you can run a simple test, by inserting the below code inside a webpage, and saving the page with a .shtml extension (the most common extension configured to parse SSI by default):

test.shtml source:

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

When you run test.shtml in your browser, you should see the current date plus time of your server displayed:

Thursday, 06-Sep-2007 20:27:27 EDT

If not, you can either ask your web host about SSI support for your account, or try and manually enable SSI, by reading "Enabling SSI on my server."

The most common usage of SSI is to include the contents of an external file onto a page or across multiple pages on your site. Modify the external file, and all pages that have this file embedded is also updated with the modified information. For a site that uses the same header, navigational menu, or footer across pages, for example, this can save you countless time and energy. The syntax to embed the contents of an external file onto the current page is:

<!--#include file="external.htm"-->

<!--#include virtual="/external.htm"-->

Which one to use depends on where "external.htm" is located. The first command assumes that the file is located in the same directory as the document containing it while the second syntax uses an absolute reference to "external.htm" starting from your root HTML directory. Typically you'll want to turn to the second syntax, as the external files to include most likely will be in a central directory while the pages including them are scattered across different directories. Here are a couple of more examples of the second syntax:

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

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

With the first code, I'm telling the server to look for "navbar.txt" inside the "includes" directory that's directly beneath the root HTML directory (ie: http://www.mysite.com/includes), while in the second code, I'm simply telling it to look in the parent directory of the page that's including "navbar.txt"

As shown, you're also not limited to just including .htm files, but other static text files such as .txt. You cannot, however, include .cgi files using this syntax without additional configuration to your server. Just FYI, both the left menu and copyright footer on this page and across the site are dynamically included using SSI using two external files. To update the copyright notice for example, all I have to do is make one simple modification to one of these files, and the changes are reflected across the entire site.

Another common and practical usage of SSI is to display basic information about your server or your visitors, such as the last modified date of the webpage, current server time, visitor IP address etc. These are all tasks that client side languages such as JavaScript cannot accomplish, but can be done using the #echo command of SSI.. Here's a quick overview of some of variables you can use with SSI's #echo to display useful information:

To echo something using SSI, the syntax is:

<!--#echo var="VARIABLE HERE" -->

Lets see how to use these variables exactly.

Echo current server date and time

To display the current server date and time, use either the "DATE_GMT" or "DATE_LOCAL" variable. In its simplest form:

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

Output: Thursday, 06-Sep-2007 20:27:58 EDT

Not bad eh for one simple line of code.

Echo last modified date of current document or file

It's very useful at times to show the last modified date of a web page:

This document last modified: <!--#echo var="LAST_MODIFIED" -->

Output: This document last modified: Saturday, 04-Mar-2006 03:41:24 EST

Echo last modified date of any document or file

You can also display the last modified date of any document or file on your server besides the present, by using another command called #flastmod instead of #echo:

greenday.mp3 last modified: <!--#flastmod file="grenday.mp3"-->
Index page last modified: <!--#flastmod virtual="/index.html"-->

Sample output: greenday.mp3 last modified Thursday, 06-Jan-2005 05:35:27 EST.

Echoing visitor IP address

This is also a commonly requested question and answer- how to display the user's IP address: 

Your IP: <!--#echo var="REMOTE_ADDR" -->

Output: Your IP: 221.15.149.120

Displaying file size of a document

Finally, you can display the file size of any document on your server using #echo, by using a different command called #fsize.

This document's file size: <!--#fsize file="current.shtml" -->
The file size of main index page: <!--#fsize virtual="/index.shtml" -->

Sample output: This document's file size: 8k

Interesting Uses of SSI

The interesting thing to note about using the output commands of SSI is that they can be embedded anywhere inside your HTML source, even in unexpected places to do interesting things. For example, you can use SSI echo to populate a JavaScript variable with the visitor's IP address, then continue to use JavaScript to react accordingly:

<script type="text/javascript">
var userIP="<!--#echo var="REMOTE_ADDR" -->"
if (userIP=="list of bad IPs to check")
alert("You are not allowed on this site.")
</script>

Another unconventional usage is to pass the current server time to the JavaScript Date object, then use JavaScript to display the current live time of your server:

var currentime="<!--#echo var="DATE_LOCAL" -->"
var serverdate=new Date(currenttime)
//rest of script

On the previous page I showed you SSI's ability to output various server information, such as the size of a file, current date and time etc. This is all great stuff, but a question that quickly follows is "Can I customize the format of the output such as of the date and time?" Sorry, got to learn to just be content! Just kidding. Yes, it's certainly possible, thanks to another SSI command called #config. Take a look at this:
<!--#config timefmt="%m/%d/%y" -->
<!--#echo var="DATE_LOCAL" -->
Output: 09/06/07
Instead of a long string containing both the date and time, I've used #config to pound things into exactly the format I want. Lets see now the various parameters of the #config command at your disposal:
CODE
PURPOSE OF CODE
Sample output
%a
abbreviated weekday name
Sun
%A
full weekday name
Sunday
%b
abbreviated month name
Jan
%B
full month name
January
%c
locale's appropriate date and time
Sun Dec 28 04:45:57 2005
%d
day of month - 01 to 31
25
%D
date as %m/%d/%y
12/25/05
%e
day of month - 1 to 31
25
%H
hour - 00 to 23
15
%I
hour - 01 to 12
03
%j
day of year - 001 to 366
361
%m
month of year - 01 to 12
12
%M
minute - 00 to 59
09
%n
insert a newline character
 
%p
string containing AM or PM
PM
%r
time as %I:%M:%S %p
06:08:05 PM
%R
time as %H:%M
15:09
%S
second - 00 to 59
02
%t
insert a tab character
 
%T
time as %H:%M:%S
15:21:07
%U
week number of year (Sunday is the first day of the week) - 00 to 53
52
%w
day of week - Sunday=0
0
%W
week number of year (Monday is the first day of the week) - 00 to 53
51
%x
Country-specific date format
12/25/05
%X
Country-specific time format
04:50:29
%y
year within century - 00 to 99
05 
%Y
year as CCYY (4 digits)
2005
%Z
timezone name
PST
Here are a couple more examples:
<!--#config timefmt="%A %d %B, %Y" -->
<!--#echo var="DATE_LOCAL" -->
Output: Thursday 06 September, 2007
<!--#config timefmt="%D %r"-->
This document last modified: <!--#echo var="LAST_MODIFIED" -->
Output: This document last modified: 03/04/06 03:41:24 AM
 Formatting file size with #config
So far on this page I've only used the #config command to format time related output. But you can also use this command on file size output:
<!--#config sizefmt="abbrev"-->
<!--#fsize file="current.shtml" -->
<!--#config sizefmt="bytes"-->
<!--#fsize file="current.shtml" -->
The first code tells the server to display the file size in abbreviated form, rounded to the nearest kilobytes. The second example obviously displays the size in bytes instead.
If you're on a Linux+Apache server that probably supports SSI but just doesn't have it enabled, you can try manually turning it on using the magical little file called .htaccess. Simply create an empty txt file called .htaccess, and add the below to it:
AddType text/html .shtml
AddHandler server-parsed .shtml
Options Indexes FollowSymLinks Includes
Then, upload this file to the root HTML directory of your server account, enabling SSI across the entire site for any web page with a .shtml extension. To isolate SSI ability to just a specific sub directory, upload this file to that directory instead.
Now, assuming this works, you should now make sure your web host allows you to manually turn on SSI. Some hosts may not like the idea of you turning on a feature without paying more, so to be safe, you should check with them first.
 Enabling SSI on regular html pages
Now, the above requires that your webpages be named with a .shtml extension in order for SSI to be enabled for that page. If you're going to be using SSI across the board, you may want to consider just turning on SSI for regular .html and .htm pages, so you don't have to rename your files or follow the .shtml convention. To do this, add the below code to your .htaccess file:
AddHandler server-parsed .html
AddHandler server-parsed .htm
Viola, SSI should now be enabled for regular HTML pages as well!

discuss this topic to forum