Staff Handbook: Skills : Server-Side Includes

Server-Side Includes are a set of commands that can be embedded in specialized HTML comments. These specialized comments are parsed by the web server, which examines every line of every html document delivered to an end user, and replaces these commands with the appropriate output. Note that to use Server-Side Includes, your web server must have support for them compiled in, and must be configured to allow their use. In some environments, files must be named with the extension .shtml or .shtm to be parsed, in our environment these extensions are not neccessary and are not supported, use the regular extension .html instead.

Server-side includes can be used to include separate files, to output variables such as the last modified time as part of a page, and even to add some intelligence to the page (i.e. if this condition exists, display this message, if not, display another message.). The advantage of using Server-Side Includes is that all of the inclusions and transformations involved take place on the server (hence server-side), so that the end user sees only finished HTML documents.

For our purposes, we're only concerned with two commands: <!--#include --> and <!--#echo -->.

<!--#include -->

This directive is used to include in its entirety the contents of another file (usually a text or html file). The included file may contain server-side directives of its own, i.e. a header for a small group of pages may include the header for a larger group to which the pages belong.

Example 1
Sample Code	<!--#include virtual="includes/example1.html" -->
What It Looks Like	At last, the chewy center...

Here's the source of example1.html

<table cellspacing="0" cellpadding="0">
    <tr>
        <td colspan="2" bgcolor="#18DE1F" align=center> </td>
        <td rowspan="2" bgcolor="#DED711" align=center> </td>
    </tr>
    <tr>
        <td rowspan="2" bgcolor="#DED711" align=center> </td>
        <td bgcolor="#FFFFFF" align=center>
        <!-- now we include another file -->
        
        <!--#include virtual="/staff/handbook/skills/ssi/includes/example2.html" -->
        </td>
    </tr>
    <tr>
        <td colspan="2" bgcolor="#1CDE20" align=center> </td>
    </tr>
</table>

As you can see, example1.html includes another file. Here's the source of the second file:

<table cellspacing="0" cellpadding="0">
    <tr>
        <td colspan="2" bgcolor="#18DE1F" align=center> </td>
        <td rowspan="2" bgcolor="#DED711" align=center> </td>
    </tr>
    <tr>
        <td rowspan="2" bgcolor="#DED711" align=center> </td>
        <td bgcolor="#FFFFFF" align=center>

        At last, the chewy center...

        </td>
    </tr>
    <tr>
        <td colspan="2" bgcolor="#1CDE20" align=center> </td>
    </tr>
</table>

<!--#echo -->

The <!--#echo --> directive allows us to display the contents of a variable within a page. We can define our own variables if we like, but more commonly we use predefined variables set by the web server itself.

Example 2
Sample Code	<p> This page was last modified on:<br> <!--#echo var="LAST_MODIFIED" --> </p> <p>You are connecting from:<br> <!--#echo var="REMOTE_HOST" --> </p>
What It Looks Like	This page was last modified on: Monday, 20-Aug-2001 14:27:32 EDT You are connecting from: dla-staff03.tower.lib.vt.edu

For a more thorough reference on Server-Side Includes, consult one of the following pages:

• http://www.carleton.ca/~dmcfet/html/ssi.html
  A very simple tutorial, none of the programming features are discussed.
• http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
  A more thorough tutorial, with examples of using server-side includes for basic logic. Be warned, a few of the examples don't work in our environment.
• http://hotwired.lycos.com/webmonkey/backend/apache_xssi/
  A mixture of introductory guides and tutorials, as well as demonstrations of more advanced concepts.
• http://httpd.apache.org/docs/mod/mod_include.html
  The documentation for the portion of our web server that provides support for server-side includes. The documentation is a bit dry, but the information is the most specifically geared towards our environment. If any of the other pages tell you to do things and they don't work, look at this page to find out why.

http://scholar.lib.vt.edu/staff/handbook/skills/ssi/index.html
(ABA updated on: Monday, 20-Aug-2001 14:27:32 EDT) updated Nov. 14, 2001 (GMc)