Your Daily Source for Apache News and Information  
Breaking News Preferences Contribute Triggers Link Us Search About
Apache Today [Your Apache News Source] To internet.com

Apache HTTPD Links
Apache XML Project
ApacheCon
The Jakarta Project
Apache Project
The Apache Software Foundation
The Java Apache Project
Apache Module Registry
The Apache FAQ
Apache-Perl Integration Project
Apache-Related Projects
PHP Server Side Scripting

  internet.com

Internet News
Internet Investing
Internet Technology
Windows Internet Tech.
Linux/Open Source
Web Developer
ECommerce/Marketing
ISP Resources
ASP Resources
Wireless Internet
Downloads
Internet Resources
Internet Lists
International
EarthWeb
Career Resources

Search internet.com
Advertising Info
Corporate Info
Apache Guide: Generating Fancy Directory Listings with mod_autoindex
Oct 9, 2000, 14 :05 UTC (11 Talkback[s]) (4210 reads) (Other stories by Rich Bowen)

By

When a user requests a directory without specifying a particular file name, Apache attempts to serve up a default document. The document served is determined by the directive DirectoryIndex, and is usually called index.html. However, if that document is not present, it is sometimes desirable to instead give a complete directory listing, permitting the user to select a file.

Directory listings are generated by the module mod_autoindex, which is compiled into Apache by default. Left to itself, it generates an uninteresting file listing, but with the techniques I'll show you in this article, you'll be able to make these listings as fancy as you like.

If your directory does not have a index.html in it, they you will get a directory listing, ordered by date, in which each filename is linked to that file for download. For each file, you are also given the last modified date of the file, and the size of the file.

There are a variety of default icons defined, so that different file types have different icons associated with them. And there's a link to the parent directory.

It's actually pretty nice, but there are some annoying things about it. The directories are interspersed amoung the files, rather than appearing at the top like most of us are used to. There's a Description column, but there's nothing actually in that column. And although files are alphabetically listed, the a's come after the Z's, rather than with the A's.

Some of the problems can be solved with the directives available in mod_autoindex.

For the whole story ...

For the full scoop on what you can do with mod_autoindex, you should see the documentation at http://www.apache.org/docs/mod/mod_autoindex.html I'm working on that while I work on this, so it should be a little more current by the time you read this.

Changing the Icons

To the left of each file name in a file listing, there's a little icon which presumably represents the type of file you're looking at. There's a pretty good selection of image files to choose from, but there are some file types missing, and occasionally you might want to have your own images, rather than the ones that ship with Apache.

There are three directives with which you can rectify this situation. These are the AddIcon, AddIconByType, and AddIconByEncoding. They let you specify a particular icon to be displayed, by file name, file type, or file encoding, respectively.

AddIcon lets you specify particular file names that should be displayed with a particular icon. The syntax of this directive is:

     AddIcon (ALT,/url/of/image.gif) filename

ALT is the alternate text to be displayed if the image does not load. filename can be a while file name, a wildcard, or some portion of a file name, such as a file extension. Examples might be:

     AddIcon (Image,/icons/image3.gif) .gif .jpg .png
     AddIcon /images/tmp.jpg *~

AddIconByType is the preferred directive, as it lets you specify an icon by mime type, rather than by file name. This allows for matching entire categories of files, rather than having to try to guess at file names.

     AddIconByType (Image,/icons/image1.gif) image/*

Finally, AddIconByEncoding lets you specify the icon by the mime encoding of the file. The syntax is the same as the other directives, and the argument is a mime-encoding:

     AddIconByEncoding /icons/compressed.gif x-compress

IndexOptions

The IndexOptions directive provides a list of options to set various features of the index listing. These options don't warrant their own directive, and so are lumped together here.

The syntax of the IndexOptions directive is:

     IndexOptions +option1 -option2 ...

Options marked with + will be included in the set of options, and those marked with - will be ommitted. Note that if you forget the + or - in that list, the last item on the list is all that you get. That is,

     IndexOptions SuppressDescription ScanHTMLTitles

is exactly the same directive as

     IndexOptions ScanHTMLTitles

And, furthermore, it overrides all previous IndexOptions directives that are already active. Don't forget the + and -!

I'm not going to go over all of the available options - see the docs - but here are a few that I like.

List Folders First

Those of you that are used to a graphical representation of your directories -- something like the Windows file explorer, for example -- are used to seeing the directories at the top of the listing, and the files below that. The default Apache view is to have the directories listed in the same alphabetic ordering as the files.

To override this behavior, use the FoldersFirst option:

     IndexOptions +FancyIndexing +FoldersFirst

Note that the FancyIndexing option is necessary for several of the options to work, including this one.

Descriptions from HTML Titles

Using the ScanHTMLTitles option, you can get a description of each HTML file in a listing by looking in the <TITLE> tag of each file. If you have written good HTML, this will give a very good idea of what each file is, before the user downloads. Note that in order to do this, Apache will need to open each file and parse it looking for a title tag. This can take a long time, and use up a lot of system resources.

Describe your Files

An exceptionally useful feature of mod_autoindex is the ability to provide descriptions for your files, and have these descriptions appear in the directory listing. This is accomplished with the AddDescription directive. As with several of these directive, you can specify exact file names, or you can give wild-cards to indicate a group of files.

     AddDescription "My dog" /images/fido.jpg
     AddDescription "PNG images" *.png

If you are in the habit of using really long file descriptions, or if you are using the ScanHTMLTitles option above, you might find that the space allocated to you for displaying a description is insufficient. You can correct oft this with the DescriptionWidth option. This is an option for the IndexOptions directive. You can specify a particular width, or you can specify ``*'', indicating that the field should be wide enough to accomodate the largest description you have.

     IndexOptions +DescriptionWidth=42

Readme Files

OK, one more. It may be desirable to display some informative text at the top of a directory list. This may be information about the files in the directory, or it might be administrative information about the server. Or whatever. The HeaderName and ReadmeName directives allow you to indicate a file that will be put at the top or bottom (respectively) of the directory listing. The argument for this directive is a filename stub. That means that if you have:

     ReadmeName README

and you have a file in that directory called README.html, that file will be displayed as the readme file for that directory.

Another neat trick here is that you can use HeaderName in conjunction with IndexOptions +SuppressHTMLPreamble, putting HTML in the header file to specify background, fonts, style sheets, or whatever you use on the rest of your site, so that the directory listing does not have to look like it does not belong to the rest of your site.

Conclusion

In the cases where you have directory listings rather than actual HTML pages, mod_autoindex can make these listings look exactly as you want them to, without having to generate custom directory listing pages for each directory.

Thanks for your feedback on my articles, and thanks for reading. Please drop me a note at if you have questions, or suggestions of topics you'd like for me to cover in future columns.

  Current Newswire:
Everything Solaris: Apache: Handling Traffic

LinuxEasyInstaller 2.0 final release

Apache 2.0.32 beta is available

Everything Solaris: Apache: The Basics

Apache Jakarta James Mailserver v2.0a2 Released

PostgreSQL v7.2 Final Release

Daemon News: Multiple webservers behind one IP address

Zend Technologies launches Zend Studio 2.0

NuSphere first to enable development of PHP web services

Covalent Technologies raises $18 million in venture capital

 Talkback(s) Name  Date
  Hmm.
It would be more fun if a CGI script could be run to generate the
directory listnings on the fly.   
  Oct 10, 2000, 07:25:32
   Re: Hmm.
It certainly can. Try
DirectoryIndex index.html /cgi-bin/genindex.cgi
Then if index.html is not found, genindex.cgi will
be called and can generate a directory listing
if it chooses.   
  Oct 10, 2000, 21:30:06
  ReadmeName and HeaderName are not used...
I have ReadmeName and HeaderName in the main config as well as a specific directive, but I do not get content from either. I have FancyIndexing turned on, and have not seen anything else that would be required (though I have tried many options). Any ideas?   
  Sep 21, 2001, 04:29:21
   Re: Re: Hmm.
Or better yet compose your own mod, that for which there is no load overhead
and speed is stunning, also you can share the data among children and configure
it to be flexible with reloading particular directory listing after some time.
All is easy and fast with mod_perl =)
  
  Oct 22, 2000, 05:28:49
  ready?
I want to know if the function Apache 1.3.9-4 is ready?   
  Oct 13, 2000, 14:24:23
  Question
hello Mr. Bowen. i'm a student of System Enginery on Colombia(South America)

...i want to know if you could send to me information about how to install a http server with apache software. I visit the page of apache.org, but i don't understand too much, please send me detail information about this topic (please step by step). The operation under the initialization files and all.

thanks a lot...   
  Oct 18, 2000, 17:35:59
   Re: Question
YOW.
download the tar ball, extract it and read the information. If you asking what
tar is, boy you got a ways to go.
Pavel   
  Oct 22, 2000, 05:31:54
  long filename
I am searching for a way to have my long filenames displayed entirely without being chopped up after the 20th character. I've seen this done at some other sites but I am not sure whether they are using apache or windoze.

Is there a way in apache?

Chris   
  Oct 29, 2000, 04:05:52
   Re: long filename
> I am searching for a way to have my long filenames displayed entirely without being chopped up after the 20th character. I've seen this done at some other sites but I am not sure whether they are using apache or windoze.
Is there a way in apache?
Chris

IndexOptions FancyIndexing SuppressDescription +NameWidth=*

If you use * it will use the largest file name as the width   
  Jan 15, 2001, 22:01:29
  Trouble with ScanHTMLTitles
I have set ' IndexOptions +ScanHTMLTitles' in the 'IfModule mod_autoindex.c' section of httpd.conf. My directory listing changes from the default display to a bulleted list, but with no description. I do have tag set to a string. Is there anything else one needs to set in order for this to work?

Any help really, really appreciated.

-Pradeep   
  Oct 31, 2000, 08:32:01
  Indexing doesn't work..
I'm trying to get my autoindexing to work here with Apache 1.3.20 but when i try to access the directory i get this error:

403 Forbidden
You don't have permission to access /secure/Techno/ on this server.

Can anybody tell me how to fix this ?

Thanks in Advance..   
  Jun 4, 2001, 17:28:43
Enter your comments below.
Your Name: Your Email Address:


Subject: CC: [will also send this talkback to an E-Mail address]
Comments:

See our talkback-policy for or guidelines on talkback content.

About Triggers Media Kit Security Triggers Login


All times are recorded in UTC.
Linux is a trademark of Linus Torvalds.
Powered by Linux 2.4, Apache 1.3, and PHP 4
Copyright 2002 INT Media Group, Incorporated All Rights Reserved.
Legal Notices,  Licensing, Reprints, & Permissions,  Privacy Policy.
http://www.internet.com/