Problem: You want to automate the creation of a menu page for a directory of files and make it look like any other page on your site.
Solution: Use the IndexOptions, HeaderName, ReadmeName, and IndexIgnore directives in an .htaccess file to instruct Apache’s automatic index generation on how to customize the file list. The code below converts the file list on the left side of Figure 1 into the page shown on the right side of Figure 1:
Options Indexes
IndexOptions FancyIndexing SuppressDescription SuppressHTMLPreamble
HeaderName header.html
ReadmeName footer.html
IndexIgnore header.html footer.html .htaccess
Figure 1. A few Apache commands make an auto-generated file list (left) more presentable.
Discussion
If the mod_autoindex module is enabled on your webserver, Apache can generate an automatic list of files when a directory on your webserver does not contain a default HTML page (typically named index.html).
If you have the ability to open and modify your Apache configuration file, check to make sure the following two lines are not commented out. The two lines you’re looking for should be near the top of the file:
LoadModule autoindex_module
-and:
AddModule mod_autoindex.c
The location of Apache’s configuration file-httpd.conf-is set at installation. The default location is /etc/httpd/conf/httpd.conf. A commented, or inactive, line in the configuration file is preceded by a pound sign (#).
Any change you make to the file will require a webserver restart to take effect (see Chapter 1, restarting web server).
Even with the module available for use, it’s a good idea to turn off the indexing option at the website root level, then turn it on for specific sub-directories as needed with an .htaccess file in that directory. If you have the ability to edit your Apache configuration file, look for the lines that define options for your entire website:
<Directory "/path/to/website/root">
...other directives...
Options -Indexes ...other options...
...other directives...
</Directory>
If the indexing option is already enabled, you can either add a minus sign before the word Indexes, or delete the word Indexes from the options list. (You’ll have to restart your webserver for the change to take effect.) Alternatively, you can use an .htaccess file in your website’s root directory: Just the one line-Options -Indexes-will do the trick.
When you want an auto-generated file list, such as for a directory of frequently modified downloads, turn indexing on with the line Options Indexes in the .htaccess file for that directory. Then, you can specify additional options that mod_autoindex can use to create the page.
The IndexOptions directive can be followed by several display options, but the first one must be FancyIndexing to make the rest work. After that, the example shown in the Solution uses the SuppressDescription option to leave that column out of my reformatted page. Since the files shown in my example are mostly PDFs and images, there’s no description to display. If the files had been HTML webpages, then I could leave out SuppressDescription and instead add the ScanHTMLTitles option, which would display the contents of each page’s title element in the Description column. Suppress options are also available to hide the last modified and size columns and disable column sorting.
The second display option I use-SuppressHTMLPreamble-prevents the indexing module from adding its own <html> , <head>, and <body> tags to the page. I’ll add those myself, along with other code for my site design, with the header.html and footer.html files listed in the third and fourth lines of the .htaccess code.
Despite its name, the ReadmeName directive specifies the file that contains the code to end the page.
Finally, I use the IndexIgnore directive to prevent certain files from appearing on the list. For my example, that’s just the header and footer files, as well as the .htaccess file itself. You can add any other files to the list that follows IndexIgnore, or use wildcard matches, such as *.pdf, to cloak specific types of files with the same extension, like this:
IndexIgnore header.html footer.html .htaccess *.pdf
See Also
Other display options not described in this Recipe provide additional ways to customize the auto-index page, such as specifications for column widths and custom icons based on file type. See Apache’s mod_autoindex documentation page at http://httpd.apache.org/docs/mod/mod_autoindex.html for more information.
Excerpted from Web Site Cookbook, Copyright 2006 O’Reilly Media Inc. Used with permission. Doug Addison is a freelance journalist and Web producer in Austin, Texas. You can contact him at doug@daddison.com.
