# Chapter 8. Custom Directory Listings

Directory listings are fully customizable in Abyss Web Server. If you do not like their standard look, you can provide the server with your listing template. Advanced users can do better by writing a script to generate custom listings.

# Defining a template

A directory listing template is defined by its:

- MIME Type: It is by default `text/html; charset=utf-8`. Since file names are provided using the UTF-8 text encoding, the template MIME type should always contain this text encoding (charset) value.

- Header: It is the header of the listing page that will be rendered.

- Body Line: It is the template of each file or directory line in the listing.

- Footer: It is the footer of the listing page.

When generating a directory listing using a template, the server creates a special XSSI environment before processing the header, the line description for every file in the listing, and the footer. So you can (in fact, you should) use XSSI directives to insert information about every file in the generated page.

While processing the line description for a given file, the server sets the following environment variables in addition to the standard CGI environment variables:

- `DIRLIST_FILE_NAME`: The name of the current file. This name is UTF-8 encoded.

- `DIRLIST_FILE_URL`: The relative URL of the current file.

- `DIRLIST_FILE_SIZE`: The size of the current file. It will be conforming to the current XSSI size format. This parameter can be configured in the XSSI section of the console or temporarily modified using the `<!-- #config sizefmt="size_format" -->` directive. If the current file is a directory, this variable is set to the `-` (hyphen) symbol.

- `DIRLIST_FILE_DATE`: The last modification date of the current file expressed in UTC (coordinated universal time). It will be conforming to the current XSSI time format. This parameter can be configured in the XSSI section of the console or temporarily modified using the `<!-- #config timefmt="time_format" -->` directive.

- `DIRLIST_FILE_LOCAL_DATE`: The last modification date of the current file expressed in local time. It will be conforming to the current XSSI time format. This parameter can be configured in the XSSI section of the console or temporarily modified using the `<!-- #config timefmt="time_format" -->` directive.

- `DIRLIST_FILE_MIME_TYPE`: The MIME type of the current file. If the file is a directory, the value of this variable is set to `Directory`.

- `DIRLIST_FILE_MIME_MAIN_TYPE`: The main MIME type of the current file. For example, if its MIME type is `text/html`, this variable will contain `text`. If the file is a directory, the value of this variable is set to `Directory`

- `DIRLIST_FILE_MIME_SUB_TYPE`: The MIME sub-type of the current file. For example, if its MIME type of is `text/html`, this variable will be set to `html`. If the file is a directory, the value of this variable will contain `Directory`.

- `DIRLIST_FILE_TYPE`: The type of the current file. It is set to `file` if the current file is a regular file, to `dir` if it is a directory, or to `parentdir` for the special directory `..` which points to the parent directory

- `DIRLIST_FILES_COUNT`: The total number of the files in the directory listing (including the regular files, the directories, and the special directory `..` if available.)

- `DIRLIST_FILE_INDEX`: The index of the current file in the listing. The value of this variable is always between 1 and `DIRLIST_FILES_COUNT`.

Example 8-1. A simple directory listing template

- MIME Type:

         text/html; charset=utf-8

- Header:

         <HTML>
           <HEAD>
             <TITLE>
               Index of <!-- #echo var="URL" encoding="reverse-url" -->
             </TITLE>
           </HEAD>

           <BODY>
             <TABLE BORDER=0>
               <TR>
                 <TD>Name</TD>
                 <TD>Size</TD>
                 <TD>Date</TD>
                 <TD>MIME Type</TD>
               </TR>

- Body Line:

               <TR>
                 <TD>
                   <A HREF="<!-- #echo var="DIRLIST_FILE_URL" -->">
                     <!-- #echo var="DIRLIST_FILE_NAME" -->
                   </A>
                 </TD>
                 <TD> <!-- #echo var="DIRLIST_FILE_SIZE" --> </TD>
                 <TD> <!-- #echo var="DIRLIST_FILE_DATE" --> </TD>
                 <TD> <!-- #echo var="DIRLIST_FILE_MIME_TYPE" --> </TD>
              </TR>

- Footer:

              </TABLE>
            </BODY>
         </HTML>