The "Server-Side Include"

Scintillating Syntax

All server-side includes within your documents are imbedded as HTML comments. This means that they all begin with "<!--" and end with "-->". The browser would ignore everything in between, if it were ever passed to the browser by the server.

Of course, it never makes it to the browser, because the server detects certain kinds of comments, interprets them as a server-side includes, and replaces the comment with the results of the include.

A comment is assumed to be a server-side include if there is a pound sign ("#") immediately after the start of the comment, with no intervening spaces. Further, some servers are very picky and require a space right before the end of the comment. As a result, a valid server-side include looks something like this:

     <!--#command tag1=value tag2=value -->

All server-side includes have a command; most have tag1 and some require tag2 as well.

There are many kinds of server-side includes. The two most popular are:

Including a file

To include a file, use one of these server-side includes:

     <!--#include file=path -->      <!--#include virtual=path -->

[NOTE: You must not insert extra spaces. The example below may not work.]

     <!-- #include file=path -->

The first form requires that path be a valid pathname relative to the directory containing the document with the server-side include. The only restriction is that ".." (parent directory) is not allowed. Thus, this form allows you to reference any file at or below the directory containing the document.

The second form requires that path be a valid path within your virtual document tree. Relative paths are allowed, of course, and are assumed to be relative to the directory containing the document. Paths starting with "/" cause the path to be resolved relative to the base document directory defined by your server's configuration file.

A handy usage of this form is to include a standard signature file (stored at the top-level of your document tree) in every document you create. Just put

     <!--#include virtual="/signature.html" -->

at the end of each document. To update your signature, just update the signature file, and each document includes the new copy automatically.

Executing a command

To execute a command, use one of these server-side includes:

!--#exec cmd=command -->
!--#include cgi=command -->

The first form passes the command to the shell for execution. Since most servers run with a restricted environment and may not have an extensive command path defined, its best to give a complete path to the command you want to execute.

The second form executes a CGI command within the cgi-bin directory defined in your server's configuration files. The command should a complete CGI invocation, relative to your cgi-bin directory.

There are several more commands and lots of other features and details, all completely documented by the folks at the National Center for Supercomputing Applications (NCSA), who thought this up to begin with. This stuff works on NCSA httpd 1.3 or later, and any NCSA derivative server.

For additional information please see NCSA's A Beginner's Guide to HTML