oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Mo' Betta Indexes
Pages: 1, 2, 3, 4, 5

Icons & Alternate Text

Big-name software companies such as Apple, Microsoft, Adobe, and Macromedia have resources to pay graphic designers to coat their offerings in eye-pleasing pixels; however, open-source developers traditionally haven't had the resources to provide the same appeal (although this situation is gradually starting to disappear, especially among the Mozilla foundation's offerings such as Firefox and Thunderbird).

The Apache httpd distribution includes a set of icons created by Kevin Hughes back when the project was under the wing of the NCSA, which are still used in the auto-index pages in default installations. And while these icons have served their purpose well, they certainly don't compare with the quality of pixel art currently being created by professionals, such as The Iconfactory.

A sampling of the icons included in Apache's distribution for use in serve-generated index pages.
Figure 4: A sampling of the icons included in Apache's distribution for use in server-generated index pages.

So one of the easiest visual alterations that can be made to your auto-index pages is to change the icons, since this can be done by simply replacing the images rather than altering the configuration file itself. Creating the icons themselves using your image editor of choice (be it the GIMP, Photoshop, or something in between) is a different matter entirely.

If you are running Apache in a development environment on your machine or somewhere else within your network, this is simply a matter of dragging and dropping (or mving, depending on your environment) the desired images to the location specified in your configuration file.

However, if you don't have permissions to modify the images (which is most likely the case in a production environment) we'll have to tell Apache to look for them somewhere else. This can be done with the Alias directive.

Alias url directoryOrFile

The Alias command, which is not strictly applicable to our indexes, allows files that are not located in your document root to be accessed as though they were. So to create a new place for our icons, we can use the command Alias /icons/ "/Library/WebServer/Icons/"

1.3.x 2.0.x

So we now have a place to store our icons; the next step is to copy some images into the folder:

An example location to store our custom icons for Apache on OS X
Figure 5: An example location to store our custom icons for Apache on OS X.

And now it's time to put our little creations to work. In order to tell Apache to use a specific icon for a given file (or series of files) in our document tree, we have to map each icon to the file(s) that will accompany the icon in our index pages. This process can be done through one of the following three directives:

AddIcon filename pattern [pattern] ...
AddIcon (ALT, filename) pattern [pattern] ...

Each pattern is a (partial) filename or wildcard expression that resolves to a filename (ex: *.html).

There are three special cases for the pattern:

  • ^^BLANK^^ is used to specify a blank icon to be used as a spacer image (web standards geeks beware!)
  • .. is used to specify a icon for the parent directory
  • ^^DIRECTORY^^ is used to specify an icon for folders

1.3.x 2.0.x

AddIconByType file mime-pattern [mime-pattern] ...
AddIconByType (alt,file) mime-pattern [mime-pattern] ...

This directive is very similar to AddIconByType, except that you specify the appropriate icon based on the files' MIME type (as listed in Apache's mime.types file), rather than its encoding.

1.3.x 2.0.x

AddIconByEncoding filename mime-encoding
[mime-encoding] ...
AddIconByEncoding (alt,file) mime-encoding
[mime-encoding] ...

This directive is similar to AddIcon, except that you specify the appropriate icon based on the files' MIME encoding, rather than its name.

1.3.x 2.0.x

Each of the above directives has an optional syntax where it is possible to specify both the file to be used in the src attribute of the img tag and the alt text. However, it is also possible to set the alt text separately, as we'll see shortly.

Because there is more than one method to specify the icon for any given file, there is a good chance that multiple directives will apply to some files in your directory tree. For example, the following two directives

AddIconByType /images/text.png text/*
AddIconByType /images/web.png text/html

will both apply to HTML files. So which icon is used? In this situation, the first directive that matches the file will take precedence. In order to achieve the desired effect, define the most specific directives first, and then fall back on generic types later in the configuration file.

In the event that none of our AddIcon directives match one or more files in our directory, then it would be nice if Apache serves up a default icon for our obscure file types. This is exactly what the DefaultIcon directive is suited for.

DefaultIcon filename 

The default icon will be used when a file doesn't match any of the directives specified in the configuration file(s). This concept is separate from the ^^BLANK^^ icon, which is used as a spacer image to indent the column headers.

1.3.x 2.0.x

That being said, let's take a look at our progress:

A sample directory listing after adding our own icons
Figure 6: A sample directory listing after adding our own icons.

Definitely an improvement over our stock page. Now let's use our spork to complement the directives that we introduced above:

IndexOptions [IconHeight[=height]]
[IconWidth[=width]] [IconsAreLinks] 

Cool Dev Icons
Cool Dev Icons

Need a few graphics to spice up those index pages? Designer Mike Matas has made available a set of 18 toolbar icons that developers can download for free from

By including the first two parameters in the configuration file, Apache will include the width and height attributes in the img tags; it should be noted that it is perfectly acceptable to include or exclude one or the other. If included, IconsAreLinks instructs Apache to place the img tag itself within the a tag that links to a file in the directory.

1.3.x 2.0.x

If the parameters IconHeight and IconWidth are not included, then the img tags for the icons will not contain the corresponding attributes. Whereas if the optional values height and width are not specified, then Apache will use the size of the icons included in the default distribution (which happen to be the rather odd size of 20 pixels wide by 22 pixels tall). So if your icons appear stretched or compressed in the index page, you'll know where the culprit is.

The following screenshot illustrates the differences made by the previous parameters; the markup in the upper window is generated without including the IndexOptions parameters we just saw, while the lower source is:

The effects of several IndexOptions parameters
Figure 7: The effects of using the IndexOptions parameters that relate to icons; image sizes are now specified and the images themselves are now included in the <a> tags.

We can also see from the above image that although the width and height attributes of the img are specified for the icons, the alt attribute of the tags is not specified for some of the files. Fixing this problem is trivial; we can specify the alt attribute of an icon through analogous methods that we just used for the src attribute:

AddAlt string pattern [pattern] ... 

This directive follows the same conventions as the AddIcon directive.

1.3.x 2.0.x

AddAltByType string mime_type [mime_type] ...

This directive follows the same conventions as the AddIconByType directive.

1.3.x 2.0.x

AddAltByEncoding string mime_encoding [mime_encoding] ... 

This directive follows the same conventions as the AddIconByEncoding directive.

1.3.x 2.0.x

The following image is a screenshot of our index page in a text-browser after adding alt attributes for our icons:

Our auto-index page as seen in a text browser
Figure 8: Our directory listing (as seen in Lynx) after adding alt attributes for our icons.

Pages: 1, 2, 3, 4, 5

Next Pagearrow