Scott Crevier's Webmaster Resources: Using Server Side Includes

Home

ASCII Character Set

Beatles Programmers Album

Internet Explorer Bug

ISO-Latin-1 Character Set

Links

Managing Shell Utilities

Netscapes Bad Rap

PDF Maker

Please Your I.T. Dept

RGB to HEX Converter

Server-Side Includes

Technical Books

UNIX man Pages

Using Server Side Includes

Table of Contents

1.0 Introduction

2.0 What is a Server-Side Include?
    2.1 How does it work?
    2.2 How do I use one?
    2.3 What can't I do with one?

3.0 Format of Include Directives
    3.1 Syntax of includes
    3.2 Tags in includes
    3.3 Valid environment variables in includes

4.0 Types of Include Directives
    4.1 echo
    4.2 exec
    4.3 flastmod
    4.4 fsize
    4.5 include
    4.6 config

5.0 Examples of Server-Side Includes
    5.1 Displaying the last modification time
    5.2 Reading file data into a Web page
    5.3 Using a standard look on all your pages
    5.4 Using a simple footer

6.0 Summary

7.0 More Information

1.0 Introduction

This document explains how you can use server-side includes in your web pages. It is intended for users who have some experience writing HTML already; in particular, it assumes that you how to create a basic Web page and how to install it in your public_html directory. This document uses the ever-popular Apache web server as it's basis. If your web server is not Apache, don't worry. All of the features explained here are supported by most major web servers.

2.0 What is a Server-Side Include?

Server-side includes are commands you can put in your Web pages that ask the web server to add information as it sends the page to the requesting browser. One kind of include simply adds the text of a file to your page; another lets your page execute a program and puts the results in the text of the page, and so forth.

These take the form of special HTML tags you put in your web pages. They are called server-side includes because the web server is asked to include the information for you.

2.1 How does it work?

All requests for your web pages go through the web server. When someone clicks on a link to your page, their web browser connects to your web server.

One way to think of the server is as a librarian. If someone in a library wants a book, he or she can go ask the librarian to find it. The librarian will look for the book, get it, and hand it over to the patron.

The server is a program that sits quietly on the machine that hosts your web site, waiting for a request. When someone tries to access your page, their browser asks our server to retrieve it. The server finds your page and sends it back. It then returns to waiting for the next request.

Normally, the web server doesn't do anything with your page. It just opens the HTML file, and sends whatever it finds. The browser at the other end gets the HTML file, and displays it, following the standard instructions you have put in it (such as making things bold, or making lists, and so forth).

Web pages with server-side includes have special instructions to the server, things it should do before it sends them out. When the server finds your page, it will recognize that you have special commands for it, and it will follow those instructions before it sends the data out.

2.2 How do I use one?

Writing a web page with server-side includes isn't difficult. The <INCLUDE> command is a little more complicated than a simple <TITLE> or a <STRONG>, but not much.

The first thing you need to do is write your page, putting your includes in the appropriate places.

Then you have to put the HTML file wherever you want it in your web directory. However, (and this is important!) the file suffix must be '.shtml' instead of '.html'.

The extra s in the filename extension tells the web server that the file needs special server processing. If you don't put the s in the filename, the server will simply ignore all of your include commands.

Incidentally, our server is configured so that it will search for the file 'index.shtml' if it can't find 'index.html'. This is so that if someone tries to open the address http://www.crevier.org/, it will find the page, regardless of the filename.

And that's all there is to it!

2.3 Any limitations?

There is one main limitation you should be aware of when using server-side includes.

Use server-side includes sparingly in your files, since they do slow them down, and place a heavier load on our server. A document with many include commands will take much longer to process; be aware of that when you use them.

3.0 Format of Include Commands

This section explains how you actually put an include command in your document, and describes the tags and the environment variables you can use in your commands.

3.1 Syntax of includes

Any server-side include takes this form in your HTML file (web page):

Notice that instead of the usual brackets (< and >) you have to add an exclamation point and two dashes at the beginning (). It's important that you remember this; the server won't know how to handle it otherwise.

The 'command' is one of the special includes you can use; a complete list is given in section <4.0>.

Each 'tag' is additional information you pass to the command (for example, if the command is to include a file, you use a tag to tell it which file). Commands take one or two tags.

3.2 Tags in includes

As I explained above, the tags are the extra information you give to the server along with the command you want it to execute. Here I'll describe the tags, and then in section <4.0> I'll show you which tags go with which commands.

There are four tags that we're interested in. (In <4.6>, when we describe the config command, I'll introduce a few more, but since they're rarely used, we won't discuss them here.)

The 'file' tag is used when you want to give the server a file name. (Not too surprising, eh?) If you want it to include data from another file, you use this tag to let it know which one. An example of use:

The file path you give is relative to the position of the web page. So, in the first example, the file 'catalog.txt' must be in the same directory as the web page; 'intro.txt' in the second example is in a subdirectory beneath the web page.

IMPORTANT: Include files can NOT be accessed from directories above the web pages' directory.

The 'virtual' tag does the same thing as 'file', except virtual gives a file relative to the top directory; that is, relative to 'http://www.crevier.org/' or to the root directory of your virtual domain.

'var' is used when you want to refer to an environment variable. These variables contain information about the file's name, the date and time, and so on. We'll list all of the environment variables in <3.2>. An example:

The last major tag is 'cgi'. CGI stands for Common Gateway Interface. web pages have the ability to call scripts (or programs) that return their results to the page. The rules they use to communicate with these programs constitute the Common Gateway Interface.

This tag is used when you want to tell the include which program to run. It is only used with the exec' command, which is explained in section <4.2>. Here's an example of how to use this tag:


 <!--#exec cgi="/cgi-bin/date"-->





3.3  Valid environment variables in includes


When the web server accesses your web page, it also has access to
information about the page. Some of this information comes in the form
of environment variables. They're called environment variables
because they describe the environment in which your web page is being
read.


You can use the 'echo' command to print these variables. Their names
and descriptions are as follows:



DOCUMENT_NAME - the name of your web page
DOCUMENT_URI - the path to your web page
DATE_LOCAL - the current date and local time
DATE_GMT - the current date and Greenwich Mean Time
LAST_MODIFIED - the time your web page was last changed
QUERY_STRING_UNESCAPED - any search string sent by the browser
REMOTE_ADDR - the IP address of the requesting browser
SERVER_NAME - the domain name of the web-server



Here are some more examples of how they're used:




 Document name:  <!--#echo var="DOCUMENT_NAME"--> 

 Last updated :  <!--#echo var="LAST_MODIFIED"--> 

 Current time :  <!--#echo var="DATE_LOCAL"--> 




It is possible to change the format of the date and time with the
'config' command. See section <4.6> for the technical details.








4.0  Types of Include Commands


There are six main types of include commands. We'll describe each one,
explaining the format of the command, and which tags you can use with
each.


The 'config' command comes last.



4.1  echo


The 'echo' command is used to print the value of any of the environment
variables listed above in section <3.3>. Thus
the only tag it takes is the 'var' tag, and the value of 'var' must be
one of those environment variables. Note that they must be in all caps
to be processed correctly.





4.2  exec

The 'exec' command is the most powerful server-side include available.
It allows you to run a CGI script, and include the output directly in
your web page.


'exec' takes the 'cgi' tag, which specifies the script you want to
run. All CGI scripts are contained in the '/cgi-bin/' directory. Here
is an example of the proper usage:



 <!--#exec cgi="/cgi-bin/date"--> 




4.3  flastmod


This command displays the date and time that file was last modified. An example of use:



 <!--#flastmod file="test.data"--> 



It takes only the 'file' and 'virtual' tags.



4.4  fsize


The 'fsize' command prints the size of the specified file. Example:



 <!--#fsize file="log.txt"--> 



It also takes the 'file' and 'virtual' tags.



4.5  include


'include' allows you to include the contents of a file in your web
page. It takes the 'file' or 'virtual' tag. Examples:



 <!--#include file="address.txt"-->
 <!--#include virtual="/internal/edu/class.dat"-->
 <!--#include file="reference/assemble/errors.txt"--> 



Included files can either be ordinary text or actually contain HTML
commands. In either case, they should not be labeled '.html', since
the included file would not be a full HTML, just part of one.


Include will insert the text of a document into the parsed document. Any included file is subject to the usual access control. This command accepts two tags:

	

	'virtual' gives a virtual path to a document on the server. You must access a normal file this way, you cannot access a CGI script in this fashion. You can, however, access another parsed document.
	
	
'file' gives a pathname relative to the current directory. ../ cannot be used in this pathname, nor can absolute paths be used. As above, you can send other parsed documents, but you cannot send CGI scripts.
	



4.6  config


This command allows you to change the formatting of the date, time, file size and error messages.
This tag is typically used near the top of the HTML document, which sets the given behavior for the whole page.
You can also use this command mutiple times in a single HTML page; this is typically done, for example, if you
want to display the date more than once in different formats.
Valid tags for 'config' are
as follows.


'timefmt' is for changing the format of times when they're printed.
The format string must be compatible with the UNIX
'strftime' call.
There are too many available options to describe them in detail here. However,
I'll give you a few examples.


Assuming that you are using <!--#echo var="DATE_LOCAL"-->
to display the current date and/or time, the following 'config' examples will
define the date formats shown:



<!--#config timefmt="%a, %d-%h-%Y at %I:%M:%S%p %Z"-->
Thu, 21-Dec-2000 at 12:14:18PM EST

<!--#config timefmt="%A, %B %e, %Y"-->
Thursday, December 21, 2000

<!--#config timefmt="%D"-->
12/21/00

<!--#config timefmt="%r"-->
12:14:18 PM



'sizefmt' controls the display of the file size. Valid values for
this tag are 'bytes,' which lists the size in bytes (for example,
987,654,321) or 'abbrev', which simply lists the number of
kilobytes or megabytes the file uses. Examples:



 <!--#config sizefmt="bytes"-->
 <!--#config sizefmt="abbrev"--> 



'config' takes no other tags than these.


'errmsg' lets you change the message the server displays if it can't
process one of the include commands. It looks like this:



 <!--#config errmsg="Sorry pal, I couldn't process that command."--> 









5.0  Examples of Server-Side Includes


Here I'll give you some complete working examples of '.shtml'
files to show you how server-side includes work.



5.1  Displaying the last modification time


This example shows how you can give the last modification time on the
current page, and it also demonstrates how to list the last modification
time of a different file



<HTML>

<HEAD>

<TITLE>Another Sample Web Page</TITLE>

</HEAD>

<BODY>

Welcome to yet another Sample Web Page!  This page hasn't been

modified since <!--#echo var="LAST_MODIFIED"-->.

<P>

However, my favorite data file, Bob, was last modified on

<!--#flastmod file="bob.txt"-->.

<P>

Wasn't that exciting?

</BODY>

</HTML>




5.2  Reading file data into a web page


Here's an example that reads text in from a set of data files.



<HTML>

    <HEAD>

    <TITLE>Another Web Sample Page</TITLE>

    </HEAD>

    <BODY>

        This Sample Page features statistics from my weekly bowling league

        <P>

	<!--#include file="bowling/week1.dat"-->

        <P>

	<!--#include file="bowling/week2.dat"-->

        <P>

	<!--#include file="bowling/week3.dat"-->

        <P>

	I guess I need to improve my average.

    </BODY>

</HTML>




5.3  Using a standard look on all your pages


This is an example that shows how you can use a standard look and feel in all pages of your web site.
For example, you could create a file called body_tag.htm  and put just your usual body tag in there. This would define any background image, background color, text color and link colors for your web pages.
If you include that file in all your HTML pages using a server-side include, then they will all have an identical look.
You could obviously do the same to put a standard footer on all your pages.



<HTML>

    <HEAD>

    <TITLE>Another Web Sample Page</TITLE>

    </HEAD>

	<!--#include virtual="/body_tag.htm"-->

        This Sample Page features statistics from my weekly bowling league

        <P>

	<!--#include file="bowling/week1.dat"-->

        <P>

	<!--#include file="bowling/week2.dat"-->

        <P>

	<!--#include file="bowling/week3.dat"-->

        <P>

	I guess I need to improve my average.

	<!--#include virtual="/footer.htm"-->

    </BODY>

</HTML>



Now, note what would happen if you want to change the background color of your entire web site from white to black. Using the above example, all you do is change that one body_tag.htm file and voila, your entire site is changed!



5.4  Using a simple footer


Here's an example that displays a simple footer that never needs to be changed.



Last updated on

<!--#config timefmt="%a, %d-%h-%Y at %I:%M:%S%p %Z"-->

<!--#echo var="LAST_MODIFIED"-->

<br>

Copyright &#169;

<!--#config timefmt="%Y"-->

<!--#echo var="DATE_LOCAL"-->

Scott Crevier, De Pere, Wisconsin



The above HTML code will generate the following text on your web page:



Last updated on Mon, 23-Aug-1999 at 02:53:29PM EDT


Copyright © 2024
Scott Crevier, De Pere, Wisconsin



Note that this example will ALWAYS show the date stamp of the current web page, and when
the year changes, it will still display the current year in the copyright.








6.0  Summary


We've seen what a server-side include is, and had a fairly complete
explanation of what options are available to you. The examples should
help you to get started.


The important points you need to remember are these.


First, remember that any HTML document with server-side includes must
have the suffix '.shtml' instead of the usual '.html'.  That's the
way the server knows it has to handle the page differently.


Be careful with the format of the includes.  They're a bit more
elaborate than ordinary HTML commands, and if you forget the exclamation
point or the dashes at the ends, the server won't recognize them.


Lastly, be aware that it will take extra time for the server to
process a file with includes, so use them sparingly in your documents.






7.0  More Information



Apache's Enabling Server-Side Includes
NSCA's Server-Side Include Tutorial