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:
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. |