Server Side Includes
One of the trickiest aspects of maintaining a site rears its head when you need to update a part of your design that occurs on every page. You’re suddenly faced with the prospect of copying and pasting new code into dozens of files. If you have used Includes, all you’ll have to do is modify the file that you’re including into the rest of your pages and they will all be updated in one fell swoop.
This page was last updated on 2012-08-21
What are SSI?
Using Server Side Includes is a technique where by you can insert the content of one file into other files. You could, for instance, have a file called navigation.ssi containing the HTML code for your navigation bar. You then add some code to the rest of your pages showing them where this include file is, in place of actually writing the HTML code into each of those pages.
When your server (the computer hosting your website that sends pages to your viewers) is asked for a page containing SSI, it first parses this page for instructions, finds the files it needs to make up the page, puts them all together and finally sends the fully-constructed page back to the reader.
If at any time you want to update your navigation bar, all you need to change is that one navigation.ssi file and every file that has it included will instantly start being sent with the updated version of the include.
Along with the obvious benefits to code maintainability, this also makes the source code of your main pages much more readable, as common elements are abstracted out into a few short files.
The Setup
Before you can use Server Side Includes, your server will need to be configured to support them. Almost all servers can do SSI, it’s just a matter of a change in the configuration files to enable them. If your hosts don’t support SSI, you might want to look for a new host.
Any file that you want to be parsed for directives will need to have the .shtml file extension. Most Apache (and otherwise) servers have been configured to treat files of this type differently, and check them for directives that need to be carried out before they are sent to the reader.
Once your filenames end in .shtml, they’ll be treated differently by your server. A .shtml file doesn’t have to have include directives in it, but the extra check that the server does on each of these files does incur a very slight performance hit, so try not to use .shtml files when they aren’t necessary.
Enabling SSI in a Directory
If you’re concerned about the performance loss that occurs by enabling SSI across a large website, you can enable it on only a single directory by creating a .htaccess file in that directory with these lines:
AddType text/html .shtml
AddHandler server-parsed .shtml
Options Indexes FollowSymLinks Includes
This will also allow you to enable SSI throughout a site if you put this .htaccess file in your root directory — useful if your server definitely supports SSI but your hosts won’t enable it in the config files.
sourcetip: Windows users may have trouble creating a file starting with a dot, as .htaccess files require. To get around this, upload your file as normal text and rename it on the server.
Of course you could just as easily make all your .html files server-parsed. This would be useful if you’ve used static HTML files and have lots of links going towards those filenames, and don’t want to change them all. Just be aware that this may well cause a serious strain on your server. A better solution is to enable Apache’s » “XBitHack”, which tells the server to parse any HTML file with it’s execute permission set.
Enabling Indexes
As you know, if you request an URL ending with a directory name, the server will usually send you back the index.html file it finds in that directory. Even some hosts that support SSI do not have their servers set up to serve the new index.shtml files as the default for a directory. If they don’t change this for you after you ask them, you can make this change through a .htaccess file in your root directory. Add this line:
DirectoryIndex index.shtml index.html
This tells the server to look for a file named index.shtml first when dealing with these requests. If that file is not found, it will serve the index.html file. Obviously, the order you put these filenames in is vital to the operation.
Including Files with #include
Though there are a few directives that can be used in server-parsed files, include is the most useful. To include a file into another .shtml file, add a line like this:
<!--#include virtual="/includes/navigation.ssi" -->
You will probably recognise this as being modelled after a HTML comment, which allows the code inside to be ignored if SSI isn’t enabled on the server. The operation couldn’t be simpler — the include directive has a virtual argument, which is the filename of the file to be included. If SSI is enabled, this directive will be replaced by the included file’s contents.
The filename can be given relatively or absolutely, but the referenced file must reside on the same server as the calling document. It is always a good idea to start at the root directory (starting the filename with a slash), so that you can use the same code to include the file into any file in your filesystem irrespective of the location of the file calling the include.
The included file only needs to be the text you want to be inserted — it doesn’t need to be a full HTML document.
If you’ve messed up the syntax of the SSI or asked for a file that doesn’t exist, an entry will be added to the error log and you’ll get back the standard SSI error message:
[an error occurred while processing this directive]
The file you include can be either plain text or text with HTML code. Either way, once it is placed into the parent page your browser won’t know any better and will treat it exactly as if it were all a single file in the first place. The file extension of the included file doesn’t matter either — people commonly use .shtml, .html, .txt, .inc or .ssi. Naming your includes with .ssi extensions and keeping them all in an /includes/ directory makes it easy to find them when you need them.
The file you include can also contain further includes itself, which will be evaluated before it is sent to be included in the calling document. These includes will need to be .shtml files too. You should be careful with this ability however, as excessive recursive including in a single file will slow your server down. You can even include CGI scripts:
<!--#include virtual="/cgi-bin/counter.cgi" -->
This will print the output of the executed CGI script to the page.
