HTML 4.0 Sourcebook
(Publisher: John Wiley & Sons, Inc.)
Author(s): Ian S. Graham
ISBN: 0471257249
Publication Date: 04/01/98

This powerful feature should not be overused, however, as every parsable file must be specially processed by the server, which can significantly slow server response. As a result, most servers come with this feature initially disabled—you have to explicitly turn it on. Each server’s documentation explains how this is done, if it is supported.

Server-side includes are well documented in the NCSA HTTPD server on-line manuals, referenced at the end of this chapter. Also referenced are several sites on the Web that provide useful interactive tutorials illustrating server-side includes.

Include Command Format

The server-side include mechanism is framed inside an HTML comment string:

<!--#include_command -->

When parsed by a server supporting this feature, the entire comment string is replaced by the output of include_command. Because the command is inside a comment string, this will not cause problems if the document is processed by a server that does not support this feature or that has this feature disabled. Such servers will simply deliver the document, including the comment line, and the client will treat the string as a comment and ignore it.

The general form for the include command is:

<!--#command arg1=“value1”  arg2=“value2” -->

where command is the name of the command to be executed and arg1 and arg2 are arguments passed to the command. There must be no space between the hash sign (#) and the command name, or between the hash sign and the leading double dash (--#). The number and name of the argument(s) depend on the actual command; most commands take a single argument. Note that, despite its structure, this is not a comment statement. You cannot include comment descriptions inside an include command. Consequently, lines like

<!--#command arg1=“value1” This prints the time of day -->

are invalid.

There are six SSI commands: config, include, echo, fsize, flastmod, and exec. Config configures the way the server parses the document. Include includes another document (not a CGI program) at the indicated location, while echo includes the contents of one of the special environment variables that are set for parsed documents. Fsize and flastmod are similar to echo; fsize prints the size of a specified file, while flastmod prints the last modification date of a specified file. Finally, exec executes a single-line Bourne-shell command, or a CGI program. For security reasons, the exec facility can be disabled in the server configuration files, while leaving the other features operational.

The next sections describe each of these commands, and how they work; entries in italics are variables to be set by the document author. Table 11.1 summarizes the commands and the allowed forms.

Include—Include Another Document

This directive includes another document (or another parsed document) at the given location in the current document—it cannot include CGI program output. Include takes two arguments to specify the file to be included. These are:

virtual=“virtual-path/file”

Specifies the virtual path to the document, relative to the server’s document directory or to a user’s personal server directory. For example, user fosdick with his or her own public HTML area would access files in this area with the virtual path:

<!--#include virtual=“~fosdick/path/file.html” -->
file=“relative-path/file”

Specifies the path to the document relative to the current URL. For example, to include the file junk.html from the same directory, or the file blog.html from the subdirectory muck, you would use:

<!--#include file=“junk.html” -->
<!--#include file=“muck/blog.html” -->

You cannot use this form to move up in the hierarchy, only down (e.g., you can’t use ../stuff.html).

Echo—Include Value of a Variable

This includes the contents of a named environment variable. The variable is indicated by the argument var="“var_name”, where var_name can be any of the CGI environment variables listed in Tables 10.2 and 10.3 (except QUERY_STRING and PATH_INFO—see the discussion of the exec include mechanism later in this section) or one of the special environment variables listed in Table 11.2, valid only in parsable files or in CGI programs called from a parsable file.

Fsize—Include Size of Listed File

This includes the size, in bytes, of a file—the file can be specified using either the file or virtual arguments, as described in the include command section.