Server-Side Includes

One popular feature of Apache is the ability to process server-side includes, or calls to internal Apache functions that are embedded into plain HTML files and processed by Apache before being sent to the browser. Server-side includes let you perform feats from simply echoing environment variables into a page to importing modular HTML fragments or executing server-side programs each time the page is requested.

Server-side includes are embedded into what's known as parsed HTML, which is effectively just regular HTML that Apache parses (processes for embedded command tokens) when the page is requested. Apache searches through parsed HTML for server-side includes and processes each one in turn before sending them on to the client. Each include is of the following form:

<!--#command attribute=value attribute=value ... -->

Caution

The syntax of a server-side include statement is critical; it must be of exactly the form shown here. The opening string <!--#command must not contain any spaces; otherwise, Apache will treat the directive as an HTML comment and ignore it.

You can use your browser's "View Source" function to see whether any malformed server-side include statements have been ignored by Apache and passed through verbatim to the browser.

In this generic example, command can be include, exec, config, echo, or a few other possibilities. The attribute=value pairs are ways of setting or reading variables, which you can define yourself using includes or read in from the available environment variables.

First, to turn on server-side includes in Apache, uncomment the following two lines in httpd.conf (or add them to the appropriate .htaccess file):

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

Note that these lines might be found in different sections of the httpd.conf file. Make sure they both appear in the same "container" (<Directory> or <Location>). This can be difficult to determine, because some containers have a lot of comment blocks and extra text that can make the structure confusing.

Note

In Apache 2.x, the AddHandler directive is separated into a number of more specifically tasked directives; the second line in this example becomes an AddOutputFilter directive:

AddOutputFilter INCLUDES .shtml

Tip

The .shtml extension is the widely accepted UNIX standard for server-parsed HTML files; however, other variants exist, such as .shtm and .stm. To enable these as well as .shtml, make duplicates of the directive lines shown here and alter the duplicates accordingly:

AddType text/html .shtml AddHandler server-parsed .shtml AddType text/html .stm AddHandler server-parsed .stm

Next, add the Includes option to the <Directory> or <Location> block (or .htaccess file) that controls the area of the website that concerns you:

Options +Includes

The AddType directive maps a class of files (by their filename extensions) to a MIME type, extending the basic set that is stored in /usr/local/etc/apache/mime.types. The AddHandler directive assigns a handler (an internal method for Apache to process a file that is requested by the user) to a certain extensionin this case, .shtml, the traditional extension for HTML files that you want Apache to parse before serving. With these two directives in place, any .shtml file will be parsed for server-side includes on its way to the client.

Note

Aside from containing server-side includes, the only difference between .html and .shtml files is the filename extension. They're both regular HTML files. If you put a server-side include into an .html file, simply rename it to have an .shtml extension if you want it to be parsed before being sent to the browser. A server-side include in an .html or .htm file will show up unparsed in the client's HTML source for the page.

Caution

Be aware that parsing any file causes more resource drain on the CPU and memory than simply passing the file unparsed to the browser. It's best to avoid unnecessarily parsing plain HTML files; otherwise, Apache will suffer a performance hit, which might be a critical consideration for you.

A few examples of useful server-side includes follow:

• <!--#echo var="HTTP_USER_AGENT"-->

  Prints the user's browser identifier string into the page. A fuller discussion of the available environment variables will appear later in this chapter when we cover CGI programming.

• <!--#set var="email" value="[e-mail]"-->

  Sets the variable called email to the string [e-mail] for the remainder of the page (unless overridden later with a similar directive).

• <!--#include virtual="/toolbar.shtml"-->

  Embeds the contents of /toolbar.shtml into the page. SSIs are parsed recursively, so a file included this way can have its own includes.

• <!--#config timefmt="%A %B %d, %Y"-->

  Sets the time format for any server-side includes that output a date and time. The format string is the same as for the date command; see man date for more details.

• <!--#flastmod file="index.shtml"-->

  Displays the date and time that index.shtml was last modified, in the time format specified in the config timefmt example.

• <!--#exec cgi="/cgi-bin/counter"-->

  Executes a CGI script called counter and displays its output.

If you put directives like these into an .shtml file and they don't seem to be working, view the page's source. The directives should not appear in their server-side include form in the HTML code. If you see any, it means they haven't been parsed out, which means the Apache configuration hasn't been set up properly to support server-side includes.

Make sure that your AddType and AddHandler (or AddOutputFilter) directives are correctly specified and that they apply to the part of the site you're using.

Tip

The default page displayed in a directory when no filename is specified is index.html, but using the DirectoryIndex directive, you can change this or even specify a list of filenames to try:

DirectoryIndex index.php index.cgi index.html index.shtml

Apache looks for each of these files in turn in a bare directory request, and only if none are found (and Options Indexes is enabled) will it display a file listing for that directory.

If you prefer, you can simply use the following instead:

Options +MultiViews DirectoryIndex index INDEX

MultiViews tells Apache to look for any file matching the requested base filename (without the extension), and DirectoryIndex index says that any file in the directory called index.* (with any extension) should be served, generally in alphabetical preference. This way, you can account for index.htm, index.HTM, and INDEX.HTML files, however your users happen to name their files.

MultiViews can cause a performance hit, however, so you should consider your server's current CPU load before enabling MultiViews on a commonly accessed directory.

A full tutorial on server-side includes, showing everything from conditional flow-control to external CGI execution, can be found at http://httpd.apache.org/docs/1.3/howto/ssi.html.