Using Server-Side Includes at
Concentric Network
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 (advanced) 5.0 Concentric Network Scripts that Use Includes 5.1 counter: a page-hit tracker 5.2 silent-counter: counter without the feedback 5.3 randomizer: randomly chooses a line from a file 6.0 Examples of Server-Side Includes 6.1 A page-hit counter 6.2 Displaying the last modification time 6.3 Reading file data into a Web page 7.0 Summary 8.0 Where to Go for More Information
1.0 Introduction
This document explains how you can use server-side includes in your World Wide Web pages here at Concentric Research Corporation. 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 Internet Area directory.
If you are unfamiliar with how to set up your own Web pages at Concentric Network, see
our document, Designing Web Pages at Concentric Network for an introduction.
2.0 What is a Server-Side Include?
Server-side includes are commands you can put in your Web pages that ask the Concentric Network World Wide Web server to add information as it sends the page out onto the Internet. 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 at Concentric Network
is asked to include the information for you.
All requests for your Web pages go through the Concentric Network Web server.
When someone on the Internet clicks on a link to your page, their Web
browser connects to the Concentric Network server.
2.1 How does it work?
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 machines here at Concentric Network, waiting for a request. When someone on the Internet 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.
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.
2.2 How do I use one?
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 Internet
directory. However, (and this is important!) the file suffix
must be .shtml instead of .html. Important #2: You must
REPLACE your xxxxxxx.html file with the xxxxxxx.shtml version. Leaving the html version
causes the html file to be executed instead of the shtml file. Most ftp clients allow you to delete files.
The extra s tells the Concentric Network 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 has been specially designed so that it will search for the fileAnd that's all there is to it!index.shtmlif it can't findindex.html. We've done this so that if someone tries to open the addresshttp://home.concentric.net/~userID, it will find a server-include HTML as well as an ordinary one. Just a little perk.
2.3 What can't I do with one?
An odd title for a section, but there are a couple of limitations you
should be aware of in using server-side includes.
Almost all of the include commands have been made available to you. However, for security reasons, you will not be able to execute any programs in your own directory in the Internet Area. Instead, Concentric Network provides a variety of such programs for you to use, that should do just about anything you would need in your Web pages.
That's the principal restriction. We also recommend that you 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):
<!--#command tag1="value1" tag2="value2" ...-->Notice that instead of the usual brackets (< and >) you have to add an exclamation point and two dashes at the beginning (<!--) and two dashes at the end (-->). 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.
As we explained above, the tags are the extra information you give to
the server along with the command you want it to execute. Here we'll
describe the tags, and then in section <4.0> show you which tags go
with which commands.
3.2 Tags in includes
There are four tags that we're interested in. (In <4.6>, when we describe the config command, we'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:
<!--#include file="catalog.txt"-->
<!--#include file="games/intro.txt"-->
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://home.concentric.net. You probably won't ever need to use the
virtual tag.
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:
<!--#echo var="DOCUMENT_NAME"-->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>. Later on, in section <5.0>, we'll describe the scripts
available at Concentric Network specifically for this purpose. Here's an example of
how to use this tag:
<!--#exec cgi="/cgi-bin/counter"-->
3.3 Valid environment variables in includes
When the Concentric Network 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 (~userID/...)
- 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
<!--#echo var="DOCUMENT_NAME"-->
<!--#echo var="LAST_MODIFIED"-->
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, because it is somewhat technical and
not likely to be useful to most people.
The
4.1 echoecho 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.
The
4.2 execexec 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 Concentric Network scripts are contained in the /cgi-bin directory. Here
are examples of the proper usage:
<!--#exec cgi="/cgi-bin/counter"-->
<!--#exec cgi="/cgi-bin/randomizer?data.txt"-->
As with query strings, if you want to pass an argument to the CGI script,
you list it with a question mark (?) after the name of the script. So
in the second example above, the script randomizer is called, and it
is sent the file name data.txt.
NOTE: Ordinarily,Section <5.0> discusses the Concentric Network scripts designed to work with theexecalso takes thecmdtag, which allows you to run shell scripts in your Web pages. This tag has been disabled for security reasons.
exec command.
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="data.txt"-->
<!--#include virtual="/~myID/test.dat"-->
<!--#include file="reference/economics/table1.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.
4.6 config (advanced)
This command allows you to change some of the formatting of date and
time, and error messages in processing. Valid tags for config are
as follows.
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="I couldn't process that command."-->
timefmt is for changing the format of times when they're printed.
The format string must be compatible with the UNIX strftime call.
We won't describe this in further detail, as there are a large number
of formatting options; do a man strftime in the Internet Area to
see the manual page on this subject, or select here to
see the UNIX manual page on strftime.
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.
5.0 Concentric Network Scripts that Use Includes
The security around the
exec command does not allow you to run
scripts or programs from your own directory to include in an HTML file.
However, we have several scripts we are providing for your use. This
section describes the ones that are currently available.
All of our scripts are stored in the directory /cgi-bin. So, when
you want to use one in an exec command, it takes the form
<!--#exec cgi="/cgi-bin/scriptname"-->Not every CGI script is designed to work with the
exec command. The
purpose of exec is to let you run a program and include the output
in your Web page. We have a variety of CGI scripts, but most have other
uses -- in processing forms or images, for example. Make sure when you
use a CGI script with exec that it was designed to be used that way.
If there is a general-purpose script you would like to see available,
please send your suggestions to home.concentric.net. We are glad to
add scripts to our repertoire, as long as they're useful to a variety of
our subscribers.
This script lets you keep track of how many times someone has accessed
your Web page. Whenever someone connects to it, the script automatically
increments a counter in a file, and returns that number to the page for
display.
5.1 counter: a page-hit tracker
The counter script will automatically generate a file called
page.shtml.count, where page is the name of your Web page. The
file is left in your directory, together with the page. All it has in
it is the number of times the page has been accessed. If the file
doesn't exist, the script will create a new file and reset the count to
zero. (Thus, if you want to clear the count, just delete the .count
file.)
In order to use the counter, just put the following include in your Web page:
<!--#exec cgi="/cgi-bin/counter"-->wherever you want the number to appear. Make sure to rename your file to: xxxxxx.shtml. See <6.1> for an example of use.
5.2 silent-counter: counter without the feedback
This script is simply a minor variation on counter. It will access
and modify the same .count files, but when it is called it will not
print anything in the Web page. It is useful for when you want to keep
count of the number of hits, but don't want to tell the user. The syntax
for this is:
<!--#exec cgi="/cgi-bin/silent-counter"-->
5.3 randomizer: randomly chooses a line from a file
The randomizer script will take the name of a file and randomly
return one of the lines in that file. It can be used for such things
as fortune cookies, random greetings, in-line images, page-backgrounds, etc.
To use randomizer, you need to specify the name of the file. The
format is as follows:
<!--#exec cgi="/cgi-bin/randomizer?data"-->where
data is the name of the file containing the random data.
The file, an ordinary text file, can contain plain text or HTML tags such as
<IMG SRC> or <BODY BACKGROUND>. Each possible choice must be
on one line ending in a carriage return.
6.0 Examples of Server-Side Includes
Here we'll give you some complete (if very small) examples of
.shtml
files to show you how server-side includes work.
6.1 A page-hit counter
This simple example just tells the user how many times the page has
been accessed. It uses the counter script described in section
<5.1>. Here it is:
<HTML>
<TITLE>A Sample Web Page Counter</TITLE>
<BODY>
Welcome to the Sample Web Page! So far, this page has had
<!--#exec cgi="/cgi-bin/counter"--> hits!
<P>We hope you've enjoyed visiting. :)
</BODY>
</HTML>
And that's all it takes.
6.2 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>
<TITLE>Another Sample Web Page</TITLE>
<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>
Notice that you could use the counter script to
show the last time the Web page was hit: you could have the page display
the last modification time of the .count file, which would be
the last time the page was accessed. Of course, you would need to make sure
to display the last modification time before count was called.
6.3 Reading file data into a Web page
We'll round out our short examples with one that reads text in from
a set of data files.
<HTML>
<TITLE>The Last Web Sample Page</TITLE>
<BODY>
This Sample Page features a catalog of statistical data collected
each week on my Cattle Mathematics Measurement Project:
<P><!--#include file="cattle/cattle1.dat"-->
<P><!--#include file="cattle/cattle2.dat"-->
<P><!--#include file="cattle/cattle3.dat"-->
I hope you're as fascinated as I am by the statistics!
</BODY>
</HTML>
Not perhaps that interesting, but that's how they work.
7.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.
8.0 Where to Go for More Information
You can find all of Concentric Network's Web documents either in the World Wide Web Forum (WWWFORUM) library, or from the Internet Help System. You can access the Internet Help System by typing 'ihelp' at the Internet Area prompt, or by connecting to
http://home.concentric.net/support/help and choosing
The World Wide Web.
There are working examples of various server-side includes in our Web page, "Example Web Pages at Concentric Network", which is located at http://home.concentric.net/~example.
NCSA has a technical discussion of server-side includes which is available at http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html.
For general questions about the World Wide Web, or Concentric Network-specific queries, read the message system in WWWFORUM, or equivalently read our newsgroup cnc.www from the Internet Area.
You can send feedback to home.concentric.net if you have questions, comments, or suggestions; we're always glad to hear them!
Using Server-Side Includes at Concentric Network / home.concentric.net / May 11, 1995
Home | Customer Support | Contact Us | Site Map
Your Front Page | Your Personal Sites | The Clubhouse | Great Deals
Hot Stuff |
What We Do | Using This Website | Search