How to use SSI

Introduction

SSI stands for Server Side Includes, and is one of the newer parts to HTML. All of the CS department web pages have the same look and feel to them, due to their common background color, header graphic, and footer information, which is centrally maintained through SSI. It would be a huge amount of work to have to edit every page on the server to change the look of the site, or even just one of the phone numbers at the bottom of every page, so instead of that text actually being present in every .html file, there are SSI commands that tell the webserver to add in the text from other files on the fly. So when you 'view page source' from your Netscape window, it appears as if the page is all from one file, but it actually has parts coming from several different files.

.htaccess

You can use this on your personal pages as well, or on your clinic website, but you need to do a little setting up first. Create a file in the directory you want to control (e.g. ~/public_html/) called .htaccess. You can do this simply by using your favorite editor:

% emacs ~/public_html/.htaccess

This file tells the webserver what to do when someone tries to access files in your directory. There are many different things that .htaccess can control, but here we'll only focus on making SSI work. In your .htaccess file, be sure to include the following lines:

Options FollowSymLinks IncludesNOEXEC
AddType text/html .html
AddHandler server-parsed .html

That will tell the server to check all .html files for SSI commands. You could have it check .htm files as well (or other file types) simply by adding .htm to both lines:

Options FollowSymLinks IncludesNOEXEC
AddType text/html .html .htm
AddHandler server-parsed .html .htm

After you've saved the file, make sure that it's publically readable (chmod o+r ~/public_html/.htaccess), and you should be ready to start using SSI tags in your pages.

Note: If you're writing a page that's going to go in a departmental directory, the .htaccess options are already set up so you don't have to worry about them.

SSI

• <!--# is the opening identifier. An SSI token always starts with this.
• <tag> is one of the following: echo, include, fsize, flastmod, exec, config, odbc, email, if, goto, label, break
• <variable set> is a set of one or more variables and their values. The values allowed here and dependent on the tag and are listed below each tag listed below. The format of a variable set is as follows : <variable name> '=' '"' variable data '"' <variable name2> '=' '"' variable data2 '"' <variable name n> '=' '"' variable datan '"'
• --> is the closing identifier. An SSI token always ends with this.

For example, this document begins with:
<!--#include virtual="/ssi/top.ssi"-->
and ends with:
<!--#include virtual="/ssi/bottom.qref.ssi"-->
Last Modified <!--#echo var="LAST_MODIFIED"-->

top.ssi contains the code that sets up the background color, pictures at the top of the page, alignment of the text, etc. bottom.ssi lists information about the CS department, and the echo tag prints the value of the variable LAST_MODIFIED, which is maintained by the system.

Note that a comment in HTML is of the format <!-- commented text -->. The only difference between a comment and an SSI token is that an SSI token has a pound sign (<!--#), and a comment does not.

For an example of a document using ssi, see /mnt/web/www/qref/template.html.

If you want a more detailed description of what SSI can do, either of the SSI references below will be of great help to you. Here, we will only cover some of the more commonly used tags.

echo

The echo tag is used to insert the value of certain variables into an HTML document. Usage is as follows:
<!--#echo var="VARIABLE_NAME"-->, where VARIABLE_NAME is a valid variable, such as those listed below. For example, if you put "The Greenwich Mean Time is <!--#echo var="DATE_GMT"-->." into your webpage, when someone viewed it, they would see (depending, of course, on what time it was):
The Greenwich Mean Time is Friday, 05-Sep-2008 15:26:12 GMT.

Variable names can come from form fields or environment variables. If you're working with forms, you probably already know a lot about HTML and the SSI references at the bottom of this page will be very useful to you. Otherwise, you probably don't care about many of the possible variable names. Some of the more commonly used environment variable names include:

• DOCUMENT_NAME This variable is the complete local directory path of the current document.
• DOCUMENT_URI This variable is the local path of the current document referenced to the base directory of the webspace.
• DATE_LOCAL This variable is current local date and time.
• DATE_GMT This variable is the current Greenwich Mean date and time.
• LAST_MODIFIED This variable is the date and time of the last modification of the current document.
• REMOTE_ADDR This variable is the IP address of the remote client browser.
• GATEWAY_INTERFACE This variable is the name/version of the Common Gateway Interface (CGI) served on this HTTP server.
• SERVER_PROTOCOL This variable is the name/version of HTTP served on this HTTP server.
• AUTH_TYPE This variable is the authentication method used to validate the remote client.
• REMOTE_USER This variable is the user name used to validate authentication from the remote client.
• HTTP_USER_AGENT This variable is the name of the remote client browser software.
• REFERER This variable is the URL of the HTML document which referred the remote client to this document.
• FROM This variable is the name (most likely the email address) of the remote client user.

include

The include tag is used to insert the contents of a file into the HTML document at the point you are calling it from. For example, when this document includes top.ssi at the beginning, the contents of top.ssi are simply inserted before this is sent to you.

include requires one argument, which is either 'virtual' or 'real'. The format of this argument is 'virtual="filename"' or 'file="filename"'. With the virtual variable, you specify a path and filename relative to the base of the webserver. The file variable specifies a path and filename relative to the current directory. Make sure that the file you specify is globally readable (chmod o+r filename), or the web server will not be able to access it.

example: <!--#include virtual="/ssi/top.ssi"-->

References

Useful SSI references include:

• Carleton University's SSI Tutorixsal
• SSI at the Web Developer's Virtual Library

Useful .htaccess references include:

• Password protecting access to your web site with .htaccess
• Apache's bit on .htaccess
• iboost.com's brief .htaccess tutorial

Copyright (c) HMC Computer Science Department. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License.''