Tutorial on Server Includes.

This page is a brief tutorial on how to user server includes in your html documents. This information is only valid if your server is using NCSA httpd. Also, your administrator must have enabled includes for you to use them.

Author: Jeff Spirko, jas8@lehigh.edu
Date: Jan 26, 1995
Last Mod: Nov 24, 1996

It may be right or wrong, but that's not my fault. :-)

Introduction
For Lehigh Users
An Example: Signature Files
The Include Format
- include
- echo
- fsize
- flastmod
- config
Defined Variables
- DOCUMENT NAME
- DOCUMENT_URI
- QUERY_STRING_UNESCAPED
- DATE_LOCAL
- DATE_GMT
- LAST_MODIFIED
References

Section 1
Introduction to Server Includes.

According to the documentation, "NCSA httpd allows you to include the output of commands or other files in your HTML documents." -NCSA httpd docs. For example, It's really nice to have one signature file automatically included in all of your HTML documents. The documentation, however, contains information most useful to the administartors of the server, not to the users. This document is intended to help users make the most of server side includes.

The way this actually works is the server scans certain files for the occurrence of special commands called directives. They take the form of special elements in the document. For example, an element with the name !--#include tells httpd to search out another document and transmit it in place of this element. In this case, include is the name of the directive.

To quote the manual again, "Having the server parse documents is a double edged sword. It can be costly for heavily loaded servers to perform parsing of files while sending them." -NCSA httpd docs. Because of this overhead, some administrators choose not to allow server includes at all, whole most who do configure the server so it only parses files with the extension .shtml. This is so the overhead of the macro processor is not run on every single file. This means that if you have the ability to do server includes, you probably have to rename your files so they have the .shtml extension for server includes to work.

Section 2
Note for Lehigh Users.

Lehigh University runs NCSA httpd as their WWW server, and they have enabled includes, so Lehigh users can use the include directives. Remember, only files with the .shtml extension are parsed. This has been done for the convenience of the users. Please do not force them to disable the feature by abusing it. I suggest including only files in your own directory and also not including large files. Also, avoid nesting includes too far.

Section 3
An Example: Signature Files.

Here is an example of how to user server includes in your html document. The actual command format is described in the next section. For the purpose of example, I am assuming you want to include a signature in each of your html documents.

Create your signature file. Name it signature.html. It can look something like the following:
Place the following line in the document in which you want the signature to appear:

Since most servers, including Lehigh's, require it, rename that document so it has the .shtml extension.
- Note: If this is your home page, you may need to inform your administrator that this name has changed. Lehigh users can resubmit their home page to the WWW server the same way it was originally submitted.
Open up the page and see if it works. Rejoice. Drink and be merry.
Repeat steps 2 through 4 for each document you wish to "sign".

For other examples of how to use server includes, see More Examples on Lehigh University's WWW Server.

Section 4
The Include format

This information is derived from the NCSA httpd documentation.

Available directives:

include
Format:


The include directive includes the described file or URL reference in your document. You can include files to be parsed. There are two valid tags:
- file takes a pathname relative to the current directory. The parent directory (../) cannot be used in this pathname, nor can absolute paths be used.
- virtual takes a URL name. It has to be on the same server as the file including it.
echo

Format:

The echo directive prints the value of one of the include variables (defined below). Any dates are printed subject to the currently configured timefmt. The one valid tag is:
- The var tag takes the name of the variable you wish to echo.
fsize

Format:


The fsize directive prints the size of the specified file. The resulting text of this command is subject to the sizefmt parameter to the config command. The tags are the same as the above include command.
flastmod

Format:


The flastmod directive prints the last modification date of the specified file, subject to the formatting preference given by the timefmt parameter to config. The tags are the same as with the include command.
config

Format:




The config directive controls various aspects aspects of the file parsing. There are three valid tags:
- errmsg controls what message is sent back to the client if an error includes while parsing the document. When an error occurs, it is logged in the server's error log.
- timefmt gives the server a new format to use when providing dates. This is a string compatible with the strftime library call under most versions of UNIX.
- sizefmt determines the formatting to be used when displaying the size of a file. Valid choices are bytes, for a formatted byte count (formatted as 1,234,567), or abbrev for an abbreviated version displaying the number of kilobytes or megabytes the file occupies.

Section 5
Variables defined for Parsed Documents

A number of variables are made available to parsed documents. In addition to the CGI variable set, the following variables are made available:

DOCUMENT_NAME: The current filename.
DOCUMENT_URI: The virtual path to this document (such as /~robm/foo.shtml).
QUERY_STRING_UNESCAPED: The unescaped version of any search query the client sent, with all shell-special characters escaped with \.
DATE_LOCAL: The current date, local time zone. Subject to the timefmt parameter to the config command.
DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.
LAST_MODIFIED: The last modification date of the current document. Subject to timefmt like the others.