libdirbrowser Documentation

by Kagan D. macTane

1. Requirements
2. Installation Instructions
3. Security Considerations
4. Configuration


1. Requirements

This version of libdirbrowser requires that you have a web server with 
PHP enabled. Your PHP must be at least version 4.0.0. It has been 
tested on  PHP 4.3.8 running on Apache 1.3.29 and 2.0.52, both running
on Linux, but the underlying web server and operating system shouldn't
matter.

Your site visitors must be using a modern browser that supports CSS and 
the W3C DOM. libdirbrowser has been tested successfully on the follow-
ing browsers/OSes:

On Windows XP:
  * Firefox 1.0.x
  * Mozilla 1.7.x
  * MSIE 6.0
  * Opera 8.02

On MacOS 10.3.x:
  * Camino 0.9
  * Firefox 1.0.x
  * Mozilla 1.7.x
  * MSIE 5.2
  * Safari 1.2.x, 1.3, 2.0

If you find that it works successfully on some other platform, please 
contact <kmactane@gothpunk.com> to report it. Thank you.

Obviously, visitors must have JavaScript turned on. libdirbrowser makes
no attempts to verify this; you should handle that on a previous page in
your site, or edit the library to insert such functionality.



2. Installation Instructions

These instructions are intended for web developers, so they assume that
you're already familiar with JavaScript, PHP, FTP, and the general 
concepts of editing files and uploading them to servers.

  1. Figure out where you want to put things on your server.
  2. Edit getsubdirs.php and libdirbrowser.js, setting the configur-
     ation variables at the beginning of each file as desired for
     your site structure and layout. The distribution defaults
     assume getsubdirs.php will be in your site's root directory,
     that you want to allow a visitor to browse anywhere in your
     directory tree, and that you'll be putting the graphical
     folder icons in an /icons/ directory without changing the
     file names. For more details on what each variable does,
     see section 3, "Security Considerations" and section 4, 
     "Configuration".
  3. Upload the folder GIFs, getsubdirs.php and libdirbrowser.js
     to the appropriate locations on your server. Ensure that
     they're all readable by the server daemon.
  4. Optional test of getsubdirs.php: Direct a web browser to
     http://your-server-name/path/to/getsubdirs.php?dir=/
     Using MSIE or any Gecko-based browser, you should see an
     XML-document list of directories enclosed in <dir> tags.

Once things are set up on the server, you can create a web page that
includes a directory browser as follows:

  1. In the document <head>, link in the libdirbrowser.js file
     with a standard external-document <script> link.
  2. Create a <form> that includes a <select> element with an
     "id" attribute specified. (The "id" may be anything you like.)
  3. Give the <select> element the following event handler:

     onClick="toggle_item(this.options[selectedIndex].id);"

     The <select> element doesn't need to have any <option>
     elements declared in your HTML source, and if it does, the
     display will be either strange or ugly (depending on your
     tastes). I'm sorry for the validation errors this causes.
  4. Use a <body onload=""> or similar auto-loading handler that
     runs the JavaScript command:

     dirbrowser_init('id-of-your-select-element')

     Where "id-of-your-select-element" is, oddly enough, the "id" you
     chose for your <select> element.

Loading this page should now automatically display your directory 
browser.



3. Security Considerations

First of all, please note that libdirbrowser *will* give away infor-
mation about your web site's directory hierarchy. That's its basic 
purpose, after all. However, some of this information is already 
being given away by every URL you publish. 

You may have directories that are obscured in one way or another, 
such as by being "orphaned" (no links lead to them). You may also 
have directories that are password-protected, using HTTP authentica-
tion or some similar access mechanism to deny access to all except 
authorized users.

libdirbrowser *will not* respect that. It simply reads your directory 
structure straight off the hard drive, and relays information back to 
anyone who makes an HTTP GET request.

With that in mind, it does include a few protections:

* It will not read anything higher up the directory structure than
  the DOCUMENT_ROOT directory, as passed to PHP by the web server.
* The $Base_Dir variable, set in line 22, is appended to the
  DOCUMENT_ROOT, and in effect forms a further "hard limit" beyond
  which getsubdirs.php will not read. If your web-server DOCUMENT_ROOT
  is /var/www/html, and you set $Base_Dir to '/dont/go/any/higher',
  then /var/www/html/dont/go/any/higher will be the absolute highest
  directory that getsubdirs.php will read.
* If you have any directories within that one that you want omitted
  from display, you can add them to $Hide_Names. You can also use the
  $Hide_Patterns variable to use a regex match to exclude directories
  from display.
* Both $Hide_Names and $Hide_Patterns take effect recursively; if you
  put "/^hide/" in $Hide_Patterns, then *any* directory beginning with
  "hide", at *any* level of your site, will be hidden. (And if you
  forgot that you have a directory named "hideous", it will be among
  them.)
* Finally, getsubdirs.php will also skip any directory whose name
  begins with a period (dot), in accordance with Unix convention.



4. Configuration

This is a guide to each of the configuration variables found in 
getsubdirs.php and in libdirbrowser.js.

Variables in getsubdirs.php

$Base_Dir
   This sets the top-level directory to be displayed by the dir-
   browser. The display shown on the web page automatically starts 
   with the top-level directory open, and all of its subdirectories 
   closed. The $Base_Dir value is appended to the web-server value 
   for DOCUMENT_ROOT, so if your DOCUMENT_ROOT is /var/www/html, 
   and you set $Base_Dir to '/three/levels/down', the web-page 
   display will start at /var/www/html/three/levels/down (or 
   http://your-site-name.tld/three/levels/down), and can never go 
   any higher.

   If $Base_Dir is of the format '/~username', it will automatic-
   ally be expanded to '/home/username/public_html'. Trailing 
   directory names will be retained, so '/~username/somedir'becomes 
   '/home/username/public_html/somedir'.

$Hide_Names
   Any directory, at any level, whose name is found in this array 
   will be excluded from output. If your $Hide_Names array includes 
   the element 'hide', then directory /hide (and all its children, 
   such as /hide/and/seek) will be invisible, *and* directories such 
   as /visible/hide and /long/path/to/hide will also be hidden. 
   However, their sister directories /visible/clearly and 
   /long/path/to/nowhere will be shown normally.

   Matching of elements in this array is on a case-sensitive, strict-
   equivalence level; in the previous example, directories such as 
   /HIDE, /hideaway, and /visible/hideous would all be visible. For 
   more flexible (if more CPU-intensive) matching, see $Hide_Patterns.

$Hide_Patterns
   This array contains a list of regular expressions against which 
   all directories (at all levels) will be matched. Any directory 
   that matches any of the regex elements of $Hide_Patterns will be 
   excluded from display. This is more CPU-intensive than using 
   $Hide_Names (especially if you have a large number of patterns 
   in your array, or a large number of subdirectories to process), 
   but allows greater flexibility. For example, given the element 
   "/^hide/i", any directory, at any level, whose name begins with 
   "hide" in any mixture of case (hide, HIDE, hIdE, HideOut, 
   hideous, HIDEAWAY, etc.) will be omitted from display.


Variables in libdirbrowser.js

Base_Dir
   This is yet another option to limit how high up your directory tree 
   people can see. It will effectively be appended to the combined 
   DOCUMENT_ROOT + $Base_Dir variable in getsubdirs.php, so if you 
   continue the example from the $Base_Dir description above, and set 
   the JavaScript Base_Dir variable to '/then/three/more', you will 
   have effectively limited your viewers to the 
   /var/www/html/three/levels/down/then/three/more directory (which 
   would appear on the web as 
   http://your-site-name.tld/three/levels/down/then/three/more).

   Note, however, that setting this variable to something other than 
   '/' means that getsubdirs.php will be able to give away some extra 
   information that wouldn't be available graphically. You probably 
   want to leave this at its default value.

Query_URL
   The path from the page with the dirbrowser on it to the 
   getsubdirs.php executable. You can use a relative path, an abso-
   lute path, or the entire URL. If you plan to have multiple 
   dirbrowsers in multiple locations, you'll probably want to use a 
   single, absolute path (or else use multiple versions of the 
   JavaScript library).

Img_Width
   The width in pixels of the images you're using for open and closed 
   folders. Note that these images will only be displayed by Gecko-
   based browsers (Mozilla, Firefox, Netscape and Camino).

   This number is not used for an <img width="xx"> attribute, so if 
   the number entered here isn't the actual and correct pixel width, 
   it *will not* distort the image's appearance. Instead, this is 
   used to set a CSS "margin-left" property on each <option> in the 
   <select> box. If you include a few extra pixels here, it will 
   simply provide a little bit of extra space between the edge of 
   the image and the start of the words on the same line.
   
   There is no corresponding Img_Height variable because the height
   available for display is a function of the font size applied to
   the <select> box, and is affected by any font-size configuration
   the user may have done on their browser. But it usually turns out
   to be about 16 pixels.

Num_Spaces
   For browsers that can't display background images in <option> 
   fields, non-breaking spaces are used to position each directory 
   at its proper indent level. This value sets the number of spaces 
   used for each level.

Folder_Open
   The path to the opened-folder image on your server. As with 
   Query_URL, you could use a relative URL if you want, but you're 
   probably safer with an absolute one.
   
   If you change this value and use your own images instead of the
   ones supplied, you may also need to change Img_Width, above.

Folder_Closed
   The path to the closed-folder image on your server. See further 
   comments under Folder_Open.

Text_Open
   This sets the text used to indicate an opened folder for browsers 
   that can't display background images in <option> fields. If you 
   want to change the text to something other than a little minus 
   sign in parentheses, you can edit this value. Note that there's a 
   trailing space, to give some separation from the folder name itself.

Text_Closed
   This sets the text used to indicate a closed folder for browsers 
   that can't display background images in <option> fields. See 
   further comments under Text_Open.




