Using server-side includes (SSIs) to add content to your web pages

On this page: Lois Wakeman uses SSIs to add breadcrumbs, standard info and footers to pages on this site, but their use isn't just restricted to that. In this article, she explains some of the things you can, and can't, do with them.

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 link to external site 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="filename.ext" -->
<!--#include virtual="/path/filename.ext" -->

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. ../../; the second for an absolute path (e.g. in another virtual directory - /includes/, 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.


If the file includes this text:

<p>The complete contents of this site are copyright 
&copy; Lois Wakeman 1999-2008 except as expressly noted.</p>

then, if you have this code in your web page:

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

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:

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.