18.3. Adding SSI Commands to a Document
Server Side Include commands have the following format:
<!--#element attribute="value" -->
The element is one of the predefined functions that Server Side Includes can perform, such as include or echo (we'll talk more about specific elements later).
The command also includes one or more attribute/value pairs that provide the specific parameters to the function.
There are a few important things to note about SSI command syntax:
-
The whole command must be enclosed in comment indicators (<! -- ... -- >).
-
The comment terminator ( -- >) must be preceded by a space to make it clear it is not part of the SSI information.
-
The whole command must be kept on one line (line breaks between the comment tags may cause the SSI not to function).
-
The # symbol is an important part of the command and must not be omitted.
18.3.1. Example: Virtual Includes
The simplest type of Server Side Include is a " virtual include," which tells the server to add information to a file before sending it to the browser.
In this example, let's take a page from within a web site that uses a standard navigational toolbar held together with a table. Instead of placing the table in the HTML source for every web page in the site, we can just insert it into each document as follows:
<HTML> <HEAD><TITLE>News</TITLE></HEAD> <BODY> <!--#include virtual="navtable.html" --> <H1>Today's Headlines</H1> ...page contents... </BODY> </HTML>
Documents that contain SSI commands should be saved with an identifying suffix, which indicates to the server that the file should be parsed before being sent to the browser. In most cases, the suffix is .shtml (the default), but this can be configured to be any suffix, so check with your server administrator first.
The command in the above example uses the include element, which inserts the text of another document into the parsed file. The include element uses the virtual parameter to specify the URL of the document to be inserted, in this case, navtable.html. The following shows the entire contents (simplified for sake of space) of navtable.html:
<TABLE> <TR><TD><IMG SRC="toolbar.gif"></TD></TR> ...complicated toolbar stuff... </TABLE>
Technically, this should be just a fragment of an HTML document in which the structural tags (<html>, <head>, and <body>) have been omitted. This is one way to ensure the final document doesn't end up with a double (and conflicting) set of structural tags. If you have a very good reason for leaving them in, be sure they match the parsed document exactly, and keep in mind that double <body> tags aren't received well by some browsers. Otherwise, play it safe and omit them.
Many web masters label these fragments with the .htmlf suffix to keep them distinct from normal HTML documents, although it's not necessary.
The server puts the fragment in the spot indicated by the virtual include command. When the document is sent to the browser, the source looks like this:
<HTML> <HEAD><TITLE>News</TITLE></HEAD> <BODY> <TABLE> <TR><TD><IMG SRC="toolbar.gif"></TD></TR> ...complicated toolbar stuff... </TABLE> <H1>Today's Headlines</H1> ... page contents... </BODY> </HTML>
The include element is just one of the elements available through SSI. The full list of Apache 1.3 elements appears in Section 18.6, "SSI Commands" later in this chapter.
 |  |  |
| 18.2. SSI and the Server |  | 18.4. Using Environment Variables |
Copyright © 2002 O'Reilly & Associates. All rights reserved.