T.David's Script Shop - Server Side Includes Tutorial (SSI)

Over the last week many people have asked about Server Side Includes (SSI), what they are, what they do, and perhaps most importantly how to use them. I thought it might be helpful to explain SSI in a way that you might be able to use to enhance your existing websites and/or to save time doing repetitive tasks.

Server Side Includes are relatively non-complex commands that can be easily inserted into SHTML (or HTML) pages to execute CGI programs, insert files, insert a date and time stamp and more. They are not available if you are using free hosting. Why? Because at the very least you have to be able to run CGI scripts locally, since that is where the SSI derive from. Also you should understand that some hosting places disable some or all SSI commands, even though they allow CGI. Without going off on a tangent about why your hosting place might do this, I would suggest if you are paying for hosting that you get a place which allows all SSI commands, there are simply too many cool things you can do with SSI to be restricted or completely without.

There is a trade-off for using SSI though; they cause the server to work a little harder (thus slowing your page loading) because any page that has SSI on it must be executed before sending output to the browser. This is why most system administrators require you to name your .HTML (or .HTM) pages as .SHTML if the pages are going to include SSI tags. Heretofore, I am going to refer to SHTML in place of HTML unless I truly mean HTML, so try not to let these abbreviations confuse you. On the Webmaster side SSI tags are mostly straight-forward, just remember you will probably have to save your HTML pages which will include SSI tags as SHTML. By the way, it won't hurt anything if you try and run a page with SSI tags on HTML. If nothing happens, you need to switch to SHTML and if nothing happens still ... well, then your host most likely either doesn't allow the SSI command you are invoking or worse, no SSI at all.

The SSI command exec is used to execute scripts. Essentially it would do the same thing as calling the script from the browser by typing http://www.yourserver/cgi-bin/scriptname.cgi. Typical uses for SSI exec calls are counter scripts counting the visitors as they come to your page, rotating banner scripts, and executing logging scripts for security reasons. The SSI tags themselves do not show up in the source of the HTML when you do a right mouse click, instead you see the result of the executed SSI tag. It's important to remember that SSI are not the scripts themselves, but a command to execute a CGI script or invoke a system command. Normally your surfer would click a link or send a form and that would execute the CGI script, but otherwise when you need to execute a script you use the SSI exec command.

config     - sets the error-message format, time, or size
echo        - inserts the variable values of an SSI into your web page
flastmod   - inserts a date/time stamp of when a file was last updated
fsize         - will insert the size of a file into your web page
include     - insert the content of an HTML file into your web page.

How do I use SSI?

The commands above might be foreign to you, except for maybe the exec command, so let's actually put a few SSI commands to practical use for you. I really don't have the space here to get into all of the commands, but if enough people are curious about the ones I don't explain, I will write a supplementary article someday soon. Drop me a line.

Please remember: in the UNIX world (sometimes unfortuately) everything is cAsE seNsiTive, so you must keep all SSI commands in lower case as bolded above. Also the command syntax (or the way that the SSI tag looks when inserted) is mandatory. If you insert a space or omit one, then don't expect it to work.

When I first entered the Webmaster arena, my first HTML editor was Frontpage (FP). That might have some of the purists in the audiences squirming in their chairs, lol. However, one of the really neat features of FP is that you can easily insert the time/date the page was last updated.You just choose the option and voila! there it is. Now every time you update your page, the surfers will know the exact last time and date you saved the file. You can also acheive the same result with SSI by inserting the following tag in your SHTML where you want the date and time inserted using the flastmod SSI command.

This will return the result in the default date format (Note: the SSI will return the local time zone of the SERVER you are using, not YOUR timezone where you work on your pages):

Let's say you don't like this format. Good news! You can change it by using the SSI config command with the argument timefmt. Oops, I almost slipped a programming term in there: an argument is the item the command must work upon. In the flastmod example above the argument was file (thus we needed to show the time and date the file was last updated). In this particular case we will configure the time format (timefmt) to just include the date without the time.

Your next question is where did I get the %x from? Well below is a short list of other common formats you can substitute and mix to come up with your own preferred format. I have a more complete list you can use as a reference available at http://www.tdscripts.com/ssihelp.shtml

Be sure to note the use of the lowercase is different than the UPPERCASE. To mix the format around use the date code above. For example to create just the month and year, use the following SSI command:

This will result in the format:

October 1999

You can also configure that vexing message that says "an error has occured while processing this directive" by using the config errmsg argument. Maybe you don't want your surfers to know if you have an SSI problem so you could include an error message that says "Have a great day!" and then if you saw that on your page you would know that actually means there is a problem with your SSI tag.

Probably the most useful SSI command is include which will allow you to include signature files to pages, or even to combine and build full SHTML pages out of several different pages. For example, say you want to include a legal copyright notice at the bottom of every page. You could just type it in, or cut and paste to every page, but there is an easier way using SSI, plus you can change all pages with the SSI call by just modifying one file. Cool, huh?

Now save copyright.html in a directory named test on your website. Create an SSI include on an SHTML page inside the same directory by typing:

And now on each page inside the same test directory you put the above tag you will see:

But what if you want to do an SSI include on pages outside the test directory? If it is a subdirectory of test, then you are ok with the existing file argument, but if it is in any other directory outside of test then you will need to use the virtual argument instead.

The virtual argument is used to begin the search for files from the ROOT level. The ROOT level is the basically the place where you start putting your www files. When you just type your domain into the browser it pulls up the index file (by default) in your ROOT level.

Therefore the ROOT level path to the test directory would be: /test/copyright.html

Why is the virtual argument important? Well, in order to include a file you have to use the right path to it. You might compare this conceptually to using an IMG tag in your HTML programming and selecting the correct path to your image. If you don't get the path to your image correct then you will be greeted by a broken link. Now lets construct the SSI include tag using the virtual argument:

Armed with this knowledge you can see how you could use multiple SSI tags to include several different files on one SHTML page. This is a great way to update many pages at once. Although this is beyond the scope of this particular article, you can include other SHTML files which execute SSI, effectively nesting files and scripts. However you cannot include CGI scripts themselves.

I hope this helps clears up some of the mystery surrounding Server Side Includes (SSI).