Recipe 9.5. Modifying an Auto-Indexed File List to Match Your Site's Design
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.
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 9-5 into the page shown on the right side of Figure 9-5:
Options Indexes IndexOptions FancyIndexing SuppressDescription SuppressHTMLPreamble HeaderName header.html ReadmeName footer.html IndexIgnore header.html footer.html .htaccess
If the mod_autoindex module is enabled on your web server, Apache can generate an automatic list of files when a directory on your web server 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:
Figure 9-5. A few Apache commands make an auto-generated file list (left) more presentable
Any change you make to the file will require a web server restart to take effect (see Recipe 1.9).
Even with the module available for use, it's a good idea to turn off the indexing option at the web site root level, and 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 web site:
<Directory "/path/to/web site/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 web server for the change to take effect). Alternatively, you can use an .htaccess file in your web site's root directory: just the one lineOptions -Indexeswill 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 web pages, 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 useSuppressHTMLPreambleprevents 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.
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
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.