Click on our Sponsors to help Support SunWorld
Webmaster by Chuck Musciano

How to use server-side includes

Dynamic document content is easy with server-side includes

SunWorld
November  1996
[Next story]
[Table of Contents]
[Search]
Subscribe to SunWorld, it's free!
Abstract
Server-side includes transform your static documents into dynamic tools. Delivering custom content to every visitor is easier than you think. (1,750 words)


Mail this
article to
a friend
You see them all over the Web: little snippets of information that are buried in a page, and change each time you visit. Or even more mysterious, bits of information about you: your machine name and IP address. Access counts, file modification times, document sizes -- they're everywhere, and they're all created with one simple tool: the server-side include.

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.

As always, I'll be covering the specifics for NCSA and Apache servers. If you run another server, consult your documentation for the details 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 <directory> section in your server's access.conf file. To enable includes, add the includes or includesNOEXEC parameters to the directive: 

     <directory /usr/local/http/docs>
     options includes
     </directory>
Don't forget to add other needed options to the directive, like followSymLinks and indexes. At this point, don't worry about the difference between includes and includesNOEXEC; we'll cover that next month.

To prevent include processing from being performed on files in a directory, make sure includes and includesNOEXEC are not specified with the options directive.

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, the 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 the suffix .shtml. You can associate this suffix with the content type by adding this line to your srm.conf file: 

     AddType text/x-server-parsed-html .shtml
Whenever the server encounters a file with the .shtml suffix 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 srm.conf file: 

     AddType text/x-server-parsed-html .html
Whew! 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.)

Advertisements

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 commands: fsize and flastmod. The former inserts the size of a file; the latter, its last modification date. Both commands require a single tag, either file or virtual.

The 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 quotes.

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.

Echoing variables
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:

In addition, all the variables available to CGI scripts are available to the echo command. 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 command.

Like the fsize and flastmod commands, include requires either a file or 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.html and 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.html and 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 <body> tag. For example, put 

     <body bgcolor=papayawhip>
in /stdbody.html and use 
     <!--#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.html will 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.


Click on our Sponsors to help Support SunWorld

Resources

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.

What did you think of this article?
-Very worth reading
-Worth reading
-Not worth reading
 -Too long
-Just right
-Too short
 -Too technical
-Just right
-Not technical enough
 
 
 
    

SunWorld
[Table of Contents]
Subscribe to SunWorld, it's free! 		[Search]
Feedback 		[Next story]
Sun's Site

[(c) Copyright Web Publishing Inc., and IDG Communication company]

If you have technical problems with this magazine, contact webmaster@sunworld.com

URL: http://www.sunworld.com/swol-11-1996/swol-11-webmaster.html
Last modified: