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

You need to change the following directives to enable SSI on NCSA or Apache servers:

•  The Options directive—Used to enable SSI for particular directories. Edit access.conf and add Includes to the Options lines for the directories in which you want SSI to work. If a line reads Options All, SSI is already enabled for that directory. If it reads anything else, you must add Includes to the list of privileges on that line. Note that adding this line enables SSI in whatever directory you select and all subdirectories under it. So if you add this line to the server root section, you effectively enable SSI in every directory on the server.

•  The AddType directive—Used to designate the MIME type for SSI files. For example, use

AddType text/x-server-parsed-html .shtml

to enable SSI parsing for all files ending with .shtml. This information is normally stored in srm.conf. Also use

AddType application/x-httpd-cgi .cgi

if you want to allow the exec command to work. Specifying .cgi here means that all your SSI scripts must have that extension. Most srm.conf files already have these two lines, but they are commented out. Just skip down to the bottom of the file and either uncomment the existing lines or add them manually.

Learning to find the configuration files for your server, and to use the Options and AddType directives, is all you need to do to edit the configuration files.

Enabling SSI on Windows NT machines is usually a matter of naming your HTML files correctly and clicking a check box somewhere in the Configuration dialog box. Process Software’s Purveyor server uses .htp as the default filename extension for parsed files. Most other servers emulate NCSA and use .shtml instead. However, changing the extension is usually simple. Hunt up the MIME Types dialog box and add a MIME type of text/x-server-parsed for whichever filename extension you want. (As always, check your particular server’s documentation to find out whether this technique works.)

One last note on configuration: most servers allow you either to require that all SSI executables be located in your cgi-bin or Scripts directory, or require this by default. If your server doesn’t require this behavior by default, find the documentation to learn how to enable it. If the only programs that can be run are located in a known, controlled directory, the chances for errors (and hacking) are greatly reduced.

Using SSI in HTML

Now that you’ve enabled SSI on your server (or talked your system administrator into doing it for you), you’re ready to learn how to use SSI. Sit back and relax a bit. What you’ve done already is by far the hardest part. From here on, you simply need to find the syntax in your particular server’s documentation and try things out.

	Of special interest at this point is the one thing all SSI implementations have in common: all SSI commands are embedded within regular HTML comments.

Having embedded commands makes it easy to implement SSI while still making the HTML portable. A server that doesn’t understand SSI passes the commands to the browser, and the browser ignores them because they’re formatted as comments. A server that does understand SSI, however, does not pass the commands to the browser. Instead, the server parses the HTML from the top down, executing each comment-embedded command and replacing the comment with the output of the command.

This process is not as complicated as it sounds. You will go through some step-by-step examples later in this chapter, but first you’ll examine HTML comments.

HTML Comment Syntax

Because anything not tagged in HTML is considered displayable text, comments must be tagged like any other directive. Tags are always marked with angle brackets—the less-than sign (<) and greater-than sign (>)—and a keyword, which may be as short as a single letter. For example, the familiar paragraph tag, <p>, is empty, so no closing tag is necessary. Nonempty tags, such as <A href...>...</a>, enclose displayable information, or “content,” between the opening and closing tags.

The comment tag is empty and is of the form:

<!--comment text here-->

---

NOTE:  Although many servers and browsers can understand the nonstandard <!--comment text here> syntax, the remaining ones want the comment to end with -->, as required by the HTML specifications. Why? Because this lets you comment out sections of HTML code, including lines containing < and > symbols. Although not all servers and browsers require comments to end with -->, all of them will understand the syntax. Therefore, you’re better off following the standard and surrounding your comments with <!-- at the front and --> at the end.

---

In summary, an HTML comment is anything with the format <!--commenttexthere-->. Browsers know to ignore this information, and servers don’t even see it unless SSI is enabled.

Turning Comments into Commands

What happens to comments when SSI is enabled? The server looks for comments and examines the text inside them for commands. The server distinguishes comments that are really SSI commands from comments that are just comments by following a simple convention: inside the comment, all SSI commands start with a pound sign (#).

All SSI commands therefore begin with <!--#, followed by information meaningful to your server. Typically, each server supports a list of keywords, and it expects to find one of these keywords immediately following the pound sign. After the keyword are any parameters for the command—with syntax that varies both by command and by server—and then the standard comment closing (-->).