Devs.site

Apache listing customization with FancyIndexing

A web server like Apache is used mainly to display websites, yet sometimes we just want to store some files and don't have the time to create a web interface for accessing them, specially when the server itself can generate a list that can be explored from the browser.

But maybe we want to give this list a personal touch, instead of using the default boring style. This can be done with the help of a module that came with Apache 2.4 and we will see how in this little tutorial


Said module is called mod_autoindex and we might need to make sure it is enabled (it most likely is). This can be done with apachectl -M or httpd -M, if you have access to a terminal or console. Web hosting control panels have a nice interface to show what modules are loaded.

Access to the server's httpd.conf or httpd-vhost.conf files is not necessary in order to configure the module. You can directly customize it in the .htaccess file and that is all we need. Create a .htaccess files inside the folder that we want listed. Even if you are on a shared hosting.

Enable directory listing

We must tell Apache that if there's no DirectoryIndex file found in the folder (like index.html), then mod_autoindex should return the formatted listing of whatever files are inside.

Options +Indexes

To avoid a 500 Server error in case the module is not loaded, we will enclose the configuration for the module inside an IfModule section

<IfModule mod_autoindex.c>
</IfModule>

And now we are ready to enable FancyIndexing and change the style of the list. A powerful directive we must use at the beginning is IndexOptions, which can switch on and off a lot of settings related to how the directory listing is generated.

IndexOptions FancyIndexing HTMLTable FoldersFirst NameWidth=* DescriptionWidth=* XHTML IconHeight=32 IconWidth=32

What we do in the line above is enabling FancyIndexing then specifying that we want the list to be a table where folders are shown first, everything being adjusted to fit the name and description columns. Modern XHTML code should be emitted and the icons size is increased to 32 pixels. Many other settings for IndexOptions can be seen here.

An option that really gives us full control of the style of this list is IndexStyleSheet. With this we can specify the location of a CSS file that will be used for the listing.

IndexStyleSheet "css/fancy.css"

You can inspect the source code from within the browser (See source or Inspect element from the context menu) and find the selectors corresponding to each element of the listing so you can use them in the CSS file. If you use HTMLTable, then you can do stuff like

table {
    box-shadow: 0 0 5px #000;
    padding: 10px;
    width: 100%;
}

But we can also change some of the HTML code (the header above the list and the footer below it).

HeaderName HEADER.html
ReadmeName FOOTER.html

With HeaderName we specify the file that will be inserted before the list and with ReadmeName the footer. These files must not be full HTML pages starting with <html>. They must contain code that can be inserted inside a body element.

If you need to change something inside the head section, IndexHeadInsert can be used

IndexHeadInsert "<meta name=\"author\" content=\"Je\">"

A meta tag will be added inside the header of the HTML page.

With AddIcon we can specify icons for file types or specific files and directories

AddIcon icons/image.png .gif .jpg .png

This will specify what icons to use for GIF, JPG and PNG images

Lastly, you can exclude some files from the listing (for example, the CSS, icons and HTML files used to customize the list). For this, IndexIgnore can be used

IndexIgnore HEADER.html FOOTER.html

Find out more about Apache Module mod_autoindex


Code

Put all this code inside the .htaccess file

# enable directory listing if no index file found
Options +Indexes

# if module is loaded and enabled
<IfModule mod_autoindex.c>
    #   enable fancy indexing
    #   show html table
    #   folders appear first
    #   name column width is adjusted as needed
    #   xhtml code is used
    #   icons are 32 pixel wide and high
    IndexOptions FancyIndexing HTMLTable FoldersFirst NameWidth=* DescriptionWidth=* XHTML IconHeight=32 IconWidth=32

    # use style from css/fancy.css
    IndexStyleSheet "css/fancy.css"

    # insert header and footer html 
    HeaderName HEADER.html
    ReadmeName FOOTER.html

    # set icons for image files
    AddIcon icons/image.png .gif .jpg .png

    # do not show header and footer files   
    IndexIgnore HEADER.html FOOTER.html
</IfModule>

You can test this stylesheet and change it to your own liking

body {
    background-color: #574d55;
    color: #fff;
    font-family: Arial;
}

table {
    background-color: #595a68;
    box-shadow: 0 0 5px #000;
    padding: 10px;
    width: 100%;
}

a, a:visited {
    color: #fff;
    text-decoration: none;
}

h1, h2 {
    text-align: center;
}

Requirements

You will need an Apache server and access to the folder that you want to list and customize


Instructions

  1. Make sure module mod_autoindex is enabled
  2. Create a .htaccess file and add the code

0 comments

Specify your e-mail if you want to receive notifications about new comments and replies