Platinum Edition Using HTML 4, XML, and Java 1.2
(Publisher: Macmillan Computer Publishing)
Author(s): Eric Ladd
ISBN: 078971759x
Publication Date: 11/01/98

CHAPTER 32
Server-Side Includes

by Jeffry Dwight and Melissa Niles

In this chapter

SSI Specification 803

Configuring SSI 803

Using SSI in HTML 804

Common SSI Commands 806

Sample SSI Programs 810

Server Performance Considerations 833

A Web server normally doesn’t look at the files it passes along to browsers. It checks security—that is, it makes sure the caller has the right to read the file—but otherwise it just hands the file over.

A Web page is often more than one document. The most common addition is an inline graphic or two, plus a background graphic. As you learned in Chapters 28, “Programming CGI Scripts,” and 29, “Custom Database Query Scripts,” a page can contain information about other resources to display at the same time. When the browser gets back to the first page, it scans the page, determines whether more parts exist, and sends out requests for the remaining parts. This scanning and interpretation process is called parsing, and it normally happens on the client’s side of the connection.

Under certain circumstances, though, you can talk the server into parsing the document before it ever gets to the client. Instead of blindly handing over the document, ignorant of the contents, the server can interpret the documents first. When this parsing occurs on the server’s side of the connection, the process is called a server-side include (SSI).

Why include? Because the first use of server-side parsing was to allow files to be included along with the one being referenced. Programmers love abbreviations, and SSI was established quickly. Changing the term later on, when other capabilities became popular too, seemed pointless.

If you are the Webmaster for a site, you might be responsible for 50, 100, or 250 pages. Because you’re a conscientious Webmaster, you include your email address at the bottom of each page so that people can tell you about any problems. But what happens when your email address changes? Without SSI, you need to edit 50, 100, or 250 pages individually. Hope you’re a good typist!

With SSI, however, you can include your email address on each page. Your email address actually resides in one spot—say, a file called webmaster.email.txt somewhere on your server—and each page uses SSI to include the contents of this file. Then, when your email address changes, all you have to do is update webmaster.email.txt with the new information. All 250 pages referencing it will have the new information automatically and instantly.

SSI can do more than include files. You can use special commands to include the current date and time. Other commands let you report the date that a file was last modified, or its size. Yet another command lets you execute a subprogram in the manner of CGI and incorporate its output right into the flow of the text.

---

NOTE:  The hallmark of SSI, generally, is that the end result is text. If you implement an SSI page hit counter, for instance, it would report the hits using text, not inline graphical images. From your browser’s point of view, the document is all text, with nothing odd about it. SSI works without the browser’s consent, participation, or knowledge. The magic is that the text is generated on-the-fly by SSI, not hard-coded when you created the HTML file.

---

SSI Specification

Unfortunately, there is no formal set of specifications for SSI that applies to the servers of all manufacturers. There is NCSA SSI documentation available at http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html, but the syntax and usage given applies only to NCSA-style Web servers, like the Apache Web server. Even so, most Web servers follow the basic rules outlined by NCSA, and usually there are only minor variances from the basic rules. We’ll cover the rules that apply to the NCSA’s documentation because they’ll probably be compatible with the Web server you are using.

•  Unlike many protocols, options, and interfaces, SSI isn’t governed by an Internet RFC (Request For Comment) or other standard. Each server manufacturer is free to implement SSI on an ad hoc basis, including whichever commands suit the development team’s fancy and using whatever syntax strikes it as reasonable. Some servers, such as the freeware EMWAC server for Windows NT, don’t support SSI at all.

•  No one can give you a list of commands and syntax rules that apply in all situations. Most servers follow NCSA’s specification up to a point. Although you may not find the exact commands, you can probably find functions similar to those in NCSA’s arsenal.

•  Because SSI isn’t defined by a standard, server developers tend to modify their implementations of SSI more frequently than they modify other things. Even if I listed all the known servers and how they implement SSI today, the list would be out of date by the time you read this book.

•  The only way to determine which SSI functions your server supports and which syntax your server uses for each command is to find and study your server’s documentation. This chapter shows you the most common functions on the most common servers, and you’ll probably find that the syntax is valid. However, the only authority is your particular server’s documentation, so get a copy and keep it handy as you work through this chapter.

Configuring SSI

Although plenty of SSI FAQ (Frequently Asked Questions) sheets are available on the Internet, most of them are not that detailed. Configuring SSI to work on NCSA or Apache remains a common stumbling block. The other servers are a little easier to use. In addition to the NCSA site previously given, the following is one of the better sites for configuration information, and relates to the popular Apache server:
http://www.apache.org/docs/mod/mod_include.html

On most servers, SSI must be “turned on” before it will work. By default, SSI is not enabled. This is for your protection, because mismanaged SSI can be a huge security risk. For instance, what if you give any caller user on the system privileges to run any program or read any file anywhere on the server? Maybe nothing bad would happen, but that’s not the safe way to bet.

In an NCSA or Apache (UNIX) environment, you enable SSI by editing the configuration files. You must have administrative privileges on the server to edit these files, although you can probably look at them with ordinary user privileges.