What is an SSI?A server-side include is code in a web page that tells the
server to add some specified information at that point in the page. It's
a way to extend the content of your page in some useful ways.
Caution: SSIs don't work on every web
server, and the details vary from one to another. This page describes
features which I know work on Apache and Microsoft IIS servers, and are
probably applicable to others.
Ask your web hosting company if (a) you can use SSIs, (b) what file
naming conventions you have to use for them to work, and (c) where you
should keep the files that use them. Then, as long as the answer to (a)
is yes, you can get started.
How do they work?
Unless otherwise instructed, a web server just sends the content of a
web page to the client, your browser. But for an SSI to work, the
server must parse (read) the file, find all the SSIs, and process them
before sending the content to the browser.
The web server can be set up to parse all files (not usual), in which
case, you can name your files with the usual .htm
or .html extensions. However, the usual case is
to have a specific extension set up for parsed files - usually .stm, .php or .asp.
If you use the wrong extension, the SSIs will just be ignored. The
folder that holds them must have appropriate execute or scripting
permissions too, or they will not work.
What can they do?
There are three main uses: to take standard text from another file
and insert it into the page (include files), to insert the value of a
variable quantity into the page, or to run a CGI script other than as
the action of a form.
I'm going to cover the basics here: include files, and some
variables. Many ISPs forbid the running of executables this way because
it can be a security risk, so I'm not going to discuss them here. If you
want detailed information on everything that can be done, a useful
starting point is the 
Apache site, or if you have a commercial web
server, the manufacturer's site or the online help should have details
of which directives and variables are available for its product.
Including files
To include some standard text (for example, a disclaimer or
copyright), put one of these lines in your parsed web page where you
want it to appear:
<!--#include file="<em>filename.ext</em>" -->
<!--#include virtual="<em>/path/filename.ext</em>" -->
Note that although this looks like an HTML comment, you must put a
space before the closing -->. Use the first
form if the file is in the same directory or you are specifying a
relative pathname (e.g. ../../copy.inc); the
second for an absolute path (e.g. in another virtual directory - /includes/footer.inc), but never a full HTTP URL. The
file should contain either plain text or HTML markup (inbcluding scripts
of couurse), and can have any name you like, though a .inc
extension is conventional.
Example:
If the file copy.inc includes this text:
<p>The complete contents of this site are copyright <br />© Lois Wakeman 1999-2008 except as expressly noted.</p>
then, if you have this code in your web page:
<!--#include file="copy.inc" -->
you will see this in the browser:
The complete contents of this site are
copyright © Lois Wakeman 1999-2008 except as expressly
noted.
Adding variables to the page
The web server has access to certain standard variables and file
information, which you can put in your page. The most useful for the web
page author are probably:
- <!--#flastmod virtual="/path/filename.ext"
-->, and its file equivalent, which return the last modified
date for the specified file. - <!--#fsize virtual="/path/filename.ext"
-->, and its file equivalent, which return the size of the
specified file.
For example, on a downloads page, it might be useful to have this
code:
<a href="/help/styles.zip">Download</a> this file,<br />size <span class="highlight"><!--#fsize virtual="/help/styles.zip" --></span><br />(last updated on <span class="highlight"><!--#flastmod virtual="/help/styles.zip" --></span>).
which appears in the browser like:
Download
this file, size Kb
(last updated on ).
- <!--#echo var="variable" -->,
which returns one of a number of variables concerning the web server's
environment, the current page, how it was fetched, by whom, etc. Some
variables that may be useful for web pages are DOCUMENT_URI,
DATE_GMT, DATE_LOCAL,
and LAST_MODIFIED, for example:
- This document can be found at http:/
- variable DOCUMENT_URI - It's
in Uplyme - variable DATE_LOCAL - The page was last modified on
- variable LAST_MODIFIED
Pros and cons
If you have a large site with a lot of common page elements, include
files can make a big difference to how easy it is to maintain the site.
Instead of updating, say, 50 pages with the same menu or navigation bar,
you can just update the include file once.
Because all the processing is done at the server, you do not
introduce any browser compatibility problems using them. For example,
you can insert the last modified date using JavaScript, but that won't
work for everyone.
Because a page containing SSIs must be parsed, there is a small
processing overhead, but this is not generally significant in my
experience - though a very long page might be noticeably slower to load,
I guess. (But you don't have any of those, do you?)
If you have made a mistake on a parsed page (for example, an include
file cannot be found because the path is wrong), users will get a
message different from the familiar 404 error, which may confuse them
(for example, error processing test.asp file).
This is only a problem if you don't test your pages properly before
publishing them!
So, on balance, if you need the facilities offered by them, I'd say
they were worth the trouble of learning and using.
