Server Side Includes (SSI)

Server side includes are simple commands, called directives, that you insert into your HTML code, and they look like HTML comment tags. But if your Web server is set up to process SSI, the server will execute the directives before serving your Web page to the browser.

Server side includes can:

• "Echo" an environment variable (make certain information visible on the Web page, such as the current time, the date the page was last changed, the browser version, etc.).
• Include the text of another file into the Web page (for example, you can easily have the same navigation bar code automatically inserted into multiple pages).
• Execute a CGI script (run a program on the server and use its output on the page).
• Use Boolean conditionals ("if-then" logic, as in "if the browser is Netscape 4, then use the NS4 stylesheet").
• Define and use variables.

How SSI works

When a user clicks on a link in a Web page, their browser sends a request for that page to the Web server. But before the server sends off the page, it scans the code on the page to see if there are any SSI directives. If it sees none, it just serves the page to the browser. But if there any SSI in the page's code, the server will execute the SSI directives first, and then send the page to the browser. (The server is said to "parse" the page.)

If SSIs are found and executed, the server in effect re-writes some of the text on the page. This means that when you "view source" of a page using a Web browser, you can never really know if you are seeing the page's original HTML source code or if an SSI has changed something before your browser received the page.

Of course, if you view a local Web page (a page that is on your disk, not on a Web server on the Internet) any SSI will not be executed, so they won't work. The SSIs are executed by the server software (Apache on Unix). You must upload your pages to the server to test your pages with SSI.

To a Web browser SSI code looks like an HTML comment tag, so it will be completely ignored by the browser. This is what happens when you view a page locally.

Not all servers support SSI

Server side includes, and "extended server side includes" (XSSI) are part of the popular Apache Web serving software. While most servers support the use of SSI, some Web hosting providers choose not to enable it. Check with your provider; if they don't support SSI, think about finding one that does!

Naming files that contain SSI

Traditionally, pages that contain SSI are named with a ".shtml" extension, as in "page.shtml", becuse many Web servers require it. This way a server doesn't have to check the code on every page before serving it; only pages named with a ".shtml" extension are "parsed" for SSI. Check with your provider; if they support SSI, ask them if you need to name your files containing SSI with a ".shtml" extension.

SSI and PHP do not play well together

You cannot mix SSI and PHP in the same Web page. If you do, either the SSI or the PHP, or bith, will not work.

Environment variables

The server keeps track of many pieces of information that can be used by SSI commands, called "environment variables." Here is a list of environment variables generated using SSI.

The “printenv” directive

To see a list of the environment variables used by a particular server, use the printenv directive. Enclose this directive within a <pre> tag, so that each variable will be listed on its own line, as follows:

The “echo” directive

The echo directive sinply displays an environment variable on the page. To see how this works, copy the sample text from the "How to use it" column and paste it into your page's HTML code.

The “config” directive

By default, environment variables that are dates look like: "Friday, 04-Oct-2002 11:45:12 PDT". To make these dates and times look more friendly, you can use the config directive to customize the way they display.

The config directive must precede the echo directive in order to work. Simply place the config directive before the echo directive, as shown in the examples below. Note that the server parses the page (executes the directives) from top to bottom, in a linear fashion. This means a config directive will affect all echo directives that follow it, until the next config directive, which will then affect the next echo directives, etc.

The “include” directive

One of the most useful and powerful features of SSI is the ability to include the contents of one file in another. The include directive looks like this:
<!--#include virtual="filename.shtml" -->

Wherever you place this line of code, the server will replace it with the contents of "filename.shtml".

Note that the path to the included file is relative to the directory of the current page. The above example would work if both files were in the same directory. If "filename.shtml" were in a subdirectory called "includes", the code would have to look like this:
<!--#include virtual="includes/filename.shtml" -->

You must use a path to the file; you cannot use a full URL, and both files must be on the same server.

The included file can be as short or long as you like. If the included file has HTML tags in it, be careful when you insert it into your page, as it is easy to get confused and mistakenly duplicate tags.

Nesting SSI

It is possible, and often desirable, to nest an SSI inside an included file. Let's say you wanted to put a footer on the bottom of all the pages of your site that listed your copyright, name and address. Additionally, with a nested include this footer could indicate the date the page was last changed.

Because an included file is technically not a complete Web page, you could name it something like "footer.txt". This would be fine, but if the server isn't configured to execute SSI in files with a ".txt" extension, a nested include would not work. So you may wish to name your included files with a ".shtml" extension so that you can use nested SSI.

Common errors

Extra space

If you insert a space before the "#" the SSI won't be executed:

Correct:
<!--#echo var="LAST_MODIFIED" -->

Incorrect:
<!-- #echo var="LAST_MODIFIED" -->

Carriage return

If you insert a carriage return anywhere in the SSI command the SSI won't be executed:

Correct:
<!--#echo var="LAST_MODIFIED" -->

Incorrect:
<!--#echo var=
"LAST_MODIFIED" -->

Note that you may see SSI commands that appear to be broken into two lines in some of the the examples above, but that is because the browser is wrapping the lines to fit. The commands shown in this tutorial do not contain any hard returns.