How to use server-side includes
Dynamic document content is easy with server-side includes
Server-side includes transform your static documents into dynamic tools. Delivering custom content to every visitor is easier than you think. (1,750 words)
Secrets of server-side includes
Every Web server operates in the same basic mode: accept a connection from a client, validate the access, retrieve a document, and send it to the client. This model worked well when the Web was in its infancy and just delivering a document was adequate enough for all involved. Since then, delivering the same document over and over has become a bit passé. Now, people want to deliver customized content to each client, altering the document each time it is accessed. In the new operating mode, the "retrieve a document" step is followed by the "insert custom content" step. The custom results are then sent to the client.
One way to create custom content is to make every document an executable program, working within the Common Gateway Protocol (CGI) mechanism. With CGI, each URL on your server runs a program that generates a complete document on the fly. While the content is obviously customized, such programs can be overkill for most applications.
In general, most Webmasters want to take a standard document and insert just a few bits of information here and there. For them, a server-side include is just the right thing. As the name implies, text is included in the document on the server side, before the document is shipped back to the client. Usually, most of the document is static, with just a few insertions here and there. The insertion points are marked with special HTML comments that indicate the kind of data to be inserted. The server inspects each document, looking for the special comments. When one is found, the comment is removed and the desired content is inserted in its place. From the client's perspective, the document appears to have contained the text from the very beginning, with all traces of the special comments having been removed by the server.
Whipping your server into shape
By default, most servers do not look for the special server-side include comments in your documents. Enabling includes on your server is a two-step process and involves adjusting two configuration parameters for your server.
Processing includes can be a time-consuming affair for some servers,
so you may want to restrict processing to certain directories or
certain kinds of files on your server. To tell the server which
directories contain documents with server-side includes, use the
options directive within a
section in your server's
access.conf file. To enable
includes, add the
parameters to the directive:
<directory /usr/local/http/docs> options includes </directory>Don't forget to add other needed options to the directive, like
indexes. At this point, don't worry about the difference between
includesNOEXEC; we'll cover that next month.
To prevent include processing from being performed on files in a
directory, make sure
includesNOEXEC are not specified with the
With this directive in effect, files within the specified directory
and its subdirectories are candidates for includes processing, if the
files are of the right content type. To support server-side includes,
text/x-server-parsed-html content type was defined.
Files of this content type are processed by the server, which looks for the
special include comments.
Most Web servers associate a content type with a specific file
suffix. To denote files with server-side includes, some Webmasters use
.shtml. You can associate this suffix with the
content type by adding this line to your
AddType text/x-server-parsed-html .shtmlWhenever the server encounters a file with the
.shtmlsuffix in a directory with includes enabled, it will process that file for server-side includes.
For the vast majority of servers, include processing is not
expensive. For these servers, I recommend that all HTML files be
enabled for includes processing. This way, you can use server-side
includes freely in all of your documents without having to use a
special suffix. For this method, place this line in your
AddType text/x-server-parsed-html .htmlWhew! With these two changes in place, we can start using server-side includes. (Editor's note: The advertisements below are generated with server-side includes.)
Imbedding file information
All server-side includes have the same general syntax:
<!--#command tag1=value tag2=value -->There are six different commands, with various tags specific to each command. The most important part of the syntax is the five-character opening sequence:
<!--#. This is the sequence that the server searches for during includes processing. When it is found, everything up to and including the closing
-->is taken to be part of the include. That text is removed, and the result of the command is inserted in the document in its place. Remember that the closing sequence must have at least one space before it, and that the opening sequence must not have any spaces between the
#character and the command name.
To get a feel for how this works, let's start with the simplest
flastmod. The former
inserts the size of a file; the latter, its last modification date. Both
commands require a single tag, either
file tag specifies the pathname of a file relative to
the current directory containing the document being processed. The
virtual tag specifies a path relative to the root of the
server's document directory, as if it had been specified as part of a
URL on that server. For both tags, the pathname must be enclosed in
This is all easier than it sounds. Placing these lines
Size is <!--#fsize file="document.html" -->. Modified on <!--#flastmod virtual="/somedir/other.html" -->.results in this text being delivered to the client:
Size is 1K. Modified on Sunday, 29-Sep-96 21:50:58 EDT.Unfortunately, including information about a file whose name you must explicitly provide does not make for very dynamic documents.
For more dynamic data, use the
echo command to insert the
value of one of a number of predefined variables into your document.
This command requires the
var tag, which specifies the
name of the desired variable. For example,
Modified on <!--#echo var="LAST_MODIFIED" -->.inserts the last modification date of the document being processed by the server. No need to specify the file name, this command always delivers data about the current document.
There are a number of useful variables, including these:
DATE_LOCAL: The current date, local time zone.
DATE_GMT: Same as
DATE_LOCALbut in Greenwich mean time.
DOCUMENT_NAME: The current filename.
DOCUMENT_URI: The virtual path to this document.
LAST_MODIFIED: The last modification date of the current document.
QUERY_STRING_UNESCAPED: The unescaped version of any search query the client sent, with all shell-special characters escaped with \.
echocommand. Finally, your server may define additional variables; check your server documentation for details.
Including files and boilerplate
Now that you've mastered variables, the next step is to insert complete files. For that, you'll need the
include requires either a
virtual tag to provide the name of the file to include.
The contents of the file are simply inserted into the document,
replacing the include directive.
This simple action belies the fabulous capabilities of the
include command. Need to put a copyright notice at the
bottom of every page? Just add
<!--#include virtual="/copyright.html" -->at the bottom of each page and put your copyright in
copyright.html. Each document will get the copyright inserted automatically. Best of all, when the lawyers call and tell you to change the copyright, you only have to edit the single copy in
copyright.htmland all your documents are updated instantly.
All server-side includes are recursive, meaning that the text
inserted by an include is scanned for imbedded includes. This way, you
can reference other files within included files. For example,
copyright.html might contain
Copyright 1996, QuatCo Enterprises. All Rights Reserved. <!--#include virtual="disclaimer.html" -->After inserting this text, the server will discover the inclusion of
disclaimer.htmland dutifully include it as well. A number of nested levels is generally allowed by most servers; Apache currently allows 16.
Finally, don't be misled by these simple examples. Included files
can contain any text, including HTML tags. Suppose you want to ensure
that all of your documents have the same background color. You could
place a standard
<body> tag in a file and include it
in every document, in place of the regular
tag. For example, put
<!--#include virtual="/stdbody.html" -->in place of the
<body>tag in your documents. Every one will get the same background color. When you tire of papaya whip, a single change to
stdbody.htmlwill instantly change all of your documents to a new color.
Next month: The good stuff
This month, I've touched on the basics of server-side includes and given you enough details to get started. Next month, I'll conclude this tutorial with the stuff you're really waiting to hear about: dynamic content defined by programs and other executable elements. I'll also cover alternative variable formats and a few other minor details. Until then, experiment with your includes. For further information, you might want to browse the NCSA server-side include tutorial.
About the author
Chuck Musciano has been running Melmac and the HTML Guru Home Page since early 1994, serving up HTML tips and tricks to hundreds of thousands of visitors each month. He's been a beta-tester and contributor to the NCSA httpd project and speaks regularly on the Internet, World Wide Web, and related topics. His book, HTML: The Definitive Guide, is currently available from O'Reilly and Associates.
If you have technical problems with this magazine, contact firstname.lastname@example.org