Automatic index generation must be enabled with by the
Options directive's [+]Indexes
option. See the Options directive for
more details.
Status: Base
Source File:
mod_autoindex.c
Module Identifier:
autoindex_module
index.html. The DirectoryIndex
directive sets the name of this file. This is controlled by
mod_dir.mod_autoindex.Automatic index generation is enabled with using
Options +Indexes. See the Options directive for
more details.
If the FancyIndexing option is given with the IndexOptions directive, the column headers are links that control the order of the display. If you select a header link, the listing will be regenerated, sorted by the values in that column. Selecting the same header repeatedly toggles between ascending and descending order. These column header links are suppressed with IndexOptions directive's SuppressColumnSorting option.
Note that when the display is sorted by "Size", it's the actual size of the files that's used, not the displayed value - so a 1010-byte file will always be displayed before a 1011-byte file (if in ascending order) even though they both are shown as "1K".
See also: Options and DirectoryIndex.
Apache 2.0.23 reorganized the Query Arguments for Column Sorting, and introduced an entire group of new query options. To effectively eliminate all client control over the output, the IndexOptions IgnoreClient option was introduced.
The column sorting headers themselves are self-referencing hyperlinks that add the sort query options shown below. Any option below may be added to any request for the directory resource.
Note that the 'P'attern query argument is tested after the usual IndexIgnore directives are processed, and all file names are still subjected to the same criteria as any other autoindex listing. The Query Arguments parser in mod_autoindex will stop abruptly when an unrecognized option is encountered. The Query Arguments must be well formed, according to the table above.
The simple example below, which can be clipped and saved in a header.html file, illustrates these query options. Note that the unknown "X" argument, for the submit button, is listed last to assure the arguments are all parsed before mod_autoindex encounters the X=Go input.
<FORM METHOD="GET">
Show me a <SELECT NAME="F">
<OPTION VALUE="0"> Plain list
<OPTION VALUE="1" SELECTED> Fancy list
<OPTION VALUE="2"> Table list
</SELECT>
Sorted by <SELECT NAME="C">
<OPTION VALUE="N" SELECTED> Name
<OPTION VALUE="M"> Date Modified
<OPTION VALUE="S"> Size
<OPTION VALUE="D"> Description
</SELECT>
<SELECT NAME="O">
<OPTION VALUE="A" SELECTED> Ascending
<OPTION VALUE="D"> Descending
</SELECT>
<SELECT NAME="V">
<OPTION VALUE="0" SELECTED> in Normal order
<OPTION VALUE="1"> in Version order
</SELECT>
Matching <INPUT TYPE="text" NAME="P" VALUE="*">
<INPUT TYPE="submit" NAME="X" VALUE="Go">
</FORM>
AddAlt provides the alternate text to display for a
file, instead of an icon, for FancyIndexing.
File is a file extension, partial filename, wild-card
expression or full filename for files to describe.
String is enclosed in double quotes (").
This alternate text is displayed if the client is
image-incapable, has image loading disabled, or fails to
retrieve the icon.
Examples:
AddAlt "PDF" *.pdf
AddAlt "Compressed" *.gz *.zip *.Z
AddAltByEncoding provides the alternate text to
display for a file, instead of an icon, for FancyIndexing.
MIME-encoding is a valid content-encoding, such as
x-compress. String is enclosed in double
quotes ("). This alternate text is displayed if
the client is image-incapable, has image loading disabled, or
fails to retrieve the icon.
Example:
AddAltByEncoding "gzip" x-gzip
AddAltByType sets the alternate text to display for
a file, instead of an icon, for FancyIndexing.
MIME-type is a valid content-type, such as
text/html. String is enclosed in double
quotes ("). This alternate text is displayed if
the client is image-incapable, has image loading disabled, or
fails to retrieve the icon.
Example:
AddAltByType "TXT" text/plain
This sets the description to display for a file, for
FancyIndexing.
File is a file extension, partial filename, wild-card
expression or full filename for files to describe.
String is enclosed in double quotes (").
Example:
AddDescription "The planet Mars"
/web/pics/mars.gif
The typical, default description field is 23 bytes wide. 6
more bytes are added by the
IndexOptions SuppressIcon option, 7 bytes are
added by the IndexOptions SuppressSize
option, and 19 bytes are added by the
IndexOptions SuppressLastModified option.
Therefore, the widest default the description column is ever
assigned is 55 bytes.
See the DescriptionWidth IndexOptions keyword for details on overriding the size of this column, or allowing descriptions of unlimited length.
Caution: Descriptive text defined with AddDescription may contain HTML markup, such as tags and character entities. If the width of the description column should happen to truncate a tagged element (such as cutting off the end of a bolded phrase), the results may affect the rest of the directory listing.
This sets the icon to display next to a file ending in name for FancyIndexing. Icon is either a (%-escaped) relative URL to the icon, or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.
Name is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for blank lines (to format the list correctly), a file extension, a wildcard expression, a partial filename or a complete filename. Examples:
AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm
AddIcon /icons/dir.xbm ^^DIRECTORY^^
AddIcon /icons/backup.xbm *~
AddIconByType should be used in
preference to AddIcon, when possible.
This sets the icon to display next to files with FancyIndexing. Icon is either a (%-escaped) relative URL to the icon, or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.
Mime-encoding is a wildcard expression matching required the content-encoding. Examples:
AddIconByEncoding /icons/compress.xbm x-compress
This sets the icon to display next to files of type MIME-type for FancyIndexing. Icon is either a (%-escaped) relative URL to the icon, or of the format (alttext,url) where alttext is the text tag given for an icon for non-graphical browsers.
Mime-type is a wildcard expression matching required the mime types. Examples:
AddIconByType (IMG,/icons/image.xbm) image/*
The DefaultIcon directive sets the icon to display for files when no specific icon is known, for FancyIndexing. Url is a (%-escaped) relative URL to the icon. Examples:
DefaultIcon /icon/unknown.xbm
The FancyIndexing directive was replaced by the FancyIndexing option to the IndexOptions directive, and is no longer supported in Apache 2.0.
The HeaderName directive sets the name of the file that will be inserted at the top of the index listing. Filename is the name of the file to include.
Changes with Apache 1.3.7: Both HeaderName
and ReadmeName now treat
Filename as a URI path relative to the one used to
access the directory being indexed. Filename must
resolve to a document with a major content type of
"text/*" (e.g., text/html,
text/plain, etc.). This means that
filename may refer to a CGI script if the script's
actual file type (as opposed to its output) is marked as
text/html such as with a directive like:
AddType text/html .cgi
Content negotiation
will be performed if the MultiViews option is enabled. If
filename resolves to a static text/html
document (not a CGI script) and the Includes option is enabled, the file will
be processed for server-side includes (see the mod_include
documentation).
If the file specified by HeaderName contains the beginnings of an HTML document (<HTML>, <HEAD>, etc) then you will probably want to set IndexOptions +SuppressHTMLPreamble, so that these tags are not repeated.
See also ReadmeName.
The IndexIgnore directive adds to the list of files to hide
when listing a directory. File is a file extension,
partial filename, wildcard expression or full filename for
files to ignore. Multiple IndexIgnore directives add to the
list, rather than the replacing the list of ignored files. By
default, the list contains `.'. Example:
IndexIgnore README .htaccess *~
The IndexOptions directive specifies the behavior of the directory indexing. Option can be one of
If the number starts with a zero, then it is considered to be a fraction:foo-1.7 foo-1.7.2 foo-1.7.12 foo-1.8.2 foo-1.8.2a foo-1.12
foo-1.001 foo-1.002 foo-1.030 foo-1.04
IndexOptions FancyIndexing ScanHTMLTitles.
IndexOptions +ScanHTMLTitles -IconsAreLinks
FancyIndexing
IndexOptions +SuppressSize
The net effect is equivalent to
IndexOptions FancyIndexing +SuppressSize,
because the unprefixed FancyIndexing discarded
the incremental keywords before it, but allowed them to
start accumulating again afterward.IndexOptions for a
particular directory, clearing the inherited settings,
specify keywords without any '+' or '-' prefixes.
The IndexOrderDefault directive is used in combination with the FancyIndexing index option. By default, fancyindexed directory listings are displayed in ascending order by filename; the IndexOrderDefault allows you to change this initial display order.
IndexOrderDefault takes two arguments. The first must be either Ascending or Descending, indicating the direction of the sort. The second argument must be one of the keywords Name, Date, Size, or Description, and identifies the primary key. The secondary key is always the ascending filename.
You can force a directory listing to only be displayed in a particular order by combining this directive with the SuppressColumnSorting index option; this will prevent the client from requesting the directory listing in a different order.
The ReadmeName directive sets the name of the file that will be appended to the end of the index listing. Filename is the name of the file to include, and is taken to be relative to the location being indexed.
See also HeaderName, where this behavior is described in greater detail.