Hack 94 Turning on Server-Side Includes (SSI)


Server-side includes (SSIs) allow you to include other files or dynamic content in your garden variety HTML document.

Commonly, SSIs are used to include things such as headers, footers, and "What's New?" features across an entire site. When you need to change the background color of your site, for instance, you can change the header file only, and the color will be reflected immediately wherever you've included that file.

This is done by Apache before the page is actually shown to the user; he'll never know what you've included or where.

SSIs, by default, are turned off; no worries, since it's quite simple to turn them on. Open your Apache configuration file[Hack #89] and search for shtml. You should find:

# To use server-parsed HTML files
#AddType text/html .shtml
#AddHandler server-parsed .shtml

Those simple Add lines tell us a lot. They continue a pattern based on what we already know about CGI. If you recall in our Turning on CGI [Hack #92] hack, we could have turned on the CGI feature for files ending in .cgi; in other words, any file you created with the .cgi extension (whether it was a CGI program or not) would be treated as an executable script.

Likewise, these lines tell us that we can turn on the server-side include feature for files ending in .shtml. Whether we actually use the SSI feature in these files doesn't matter; they'll still be treated and processed as if they did.

This is important. You may be thinking, if SSIs are so great, why not enable them for .html filenames? Ultimately, it's a matter of speed. If you have 3,000 .html files, and only 1,000 of them actually use SSI, Apache will still look for SSI instructions in the other 2,000. That's a colossal waste of resources. Granted, processing SSI incurs very little overhead, but if you're being hit 50,000 times a second, it can certainly add up.

For now, uncomment the AddType and AddHandler lines:

# To use server-parsed HTML files
AddType text/html .shtml
AddHandler server-parsed .shtml

This will turn on the SSI mojo power. But where? When we were learning about CGI, we saw a configuration setting that said our CGIs lived in /Library/Webserver/CGI-Executables/. We need to tell Apache where we want SSI capability.

For now, we'll just assume anything in Apache's document directory, /Library/Webserver/Documents, should be allowed to use SSI. Search your configuration file for /Library/Webserver/Documents/. We're after the following piece of configuration:

<Directory "/Library/WebServer/Documents">

# This may also be "None", "All", or any combination of "Indexes",
# "Includes", "FollowSymLinks", "ExecCGI", or "MultiViews".
# Note that "MultiViews" must be named *explicitly* --- "Options All"
# doesn't give it to you.
Options Indexes FollowSymLinks MultiViews

# This controls which Options the .htaccess files in directories can
# override. Can also be "All", or any combination of "Options", "FileInfo", 
# "AuthConfig", and "Limit"
AllowOverride None

# Controls who can get stuff from this server.
Order allow,deny
Allow from all

We're going to skip the brunt of what this entire configuration means, but for now, add the word Includes to the Options line:

<Directory "/Library/WebServer/Documents">
Options Indexes FollowSymLinks MultiViews Includes

Options is an Apache directive that can turn on or off different features for the <Directory> and all subdirectories beneath it. Subdirectories can override their parent configuration. Simply by adding Includes, we're allowing SSI in the main document directory.

Because we've made changes to Apache's configuration file, we now need to restart Apache:

% sudo apachectl restart
httpd restarted

To test that our SSIs are working properly, create an index.shtml file (because .shtml is the only extension we've enabled SSIs for) in the /Library/WebServer/Documents directory, and edit to match the following snippet:

<h1>Gleefully Served By Mac OS X</h1>
<pre><!--#include virtual="/cgi-bin/test-cgi"--></pre>

Here, we're including a test CGI script into the contents of our main index page. When you load (assuming you placed index.shtml in /Library/Webserver/Documents/), you'll see our Gleefully Served message, as well as the output of the CGI script itself. We could just have easily created a static web page (say, navigation.html) and included that within our page instead.

SSI is configured and working, but what can you do with it? What if your marketing department wants to create an image gallery of the newest ads they've planned? Take a look at the SSI Image Gallery URL under See Also for one search engine-friendly way of doing it. Be sure to explore the Apache SSI documentation for more possibilities.

94.1 See Also

  • Apache Web-Serving with Mac OS X: Part 2 (http://www.macdevcenter.com/lpt/a//mac/2001/12/14/apache_two.html)

  • SSI Image Gallery (http://evolt.org/article/Search_Engine_Friendly_SSI_Image_Gallery/20/15882/index.html)

  • Apache mod_include Documentation (http://httpd.apache.org/docs/mod/mod_include.html)