README.txt in Filebrowser 5

Drupal filebrowser.module README.txt
==============================================================================

The Drupal filebrowser.module allows site administrators to expose a
particular file system folder and all of its subfolders with a fancy
FTP-like interface to site visitors. File metainformation (via descript.ion
and files.bss) is supported. The module also allows these metafiles
to store special content, which can be parsed with a callback. If no
callback is specified in the file, only the description will be
fetched.

This module tries to protect your files outside of the public folder
from being listed, as well as trying to protect version control
and webserver metafiles (CVS and .svn folders, .htaccess files) from 
being listed, but there is no guarantee as usual, that this will 
never happen. If you find a bug, feel free to submit a bug report.

Installation
------------------------------------------------------------------------------
 
  - Copy filebrowser.info and filebrowser.module to your Drupal 
    sites/all/modules/filebrowser folder
  - Enable the module as usual on Drupal's admin page
  - Provide the module settings on the administer >> site configuration >> 
    filebrowser page
 
Configuration
------------------------------------------------------------------------------

  - You need to provide a root folder for filebrowser, from where the
    folder lists will be generated.
  - The icon folder should have icons for file types used. The icons
    should be named file-txt.png, file-gif.png, etc. The default
    icon used is file-default.png if an icon is not present for 
    a particular file extension. The icon used for all folders is 
    file-folder.png.
  - You should decide whether you are about to list the description files
    to visitors or not. This is up to you, depending on your usage scenario.
  - The module suggests a menu item, so you can set the menu item to show up. 
    The filebrowser interface is available anyway at '/filebrowser' 
    (or ?q=filebrowser if you don't use clean URLs)
    
Features
------------------------------------------------------------------------------

After enabling and configuring, the module has some basic features to browse
a folder of files, going deeper or back in the folder tree. There are some
nice additions though, which you can master to make the filebrowser output
a lot more useful.

  - icons displayed for files and folders (based on their extensions)
  - basic description shown for files and folders, possible to specify
    description for current folder shown as page help
  - possibility to use custom formatted description files (see below)
    with a parser callback function
  - possibility to style the file browser page different then other
    pages (the #filebrowser-page css ID is provided)
  - possibility to completely reformat the table through the 
    theme specific definition of theme_filebrowser_page
  - defined the hook_filebrowser_pre, so that your modules can provide
    information for filebrowser pages printed before the table (eg.
    file size or uptodate status stats, or global notices you intend
    to display on all filebrowser pages)

Description file format, and custom format parsing
------------------------------------------------------------------------------

The basic description file format is to have "filename description" pairs
on every line:

README.txt         Detailed information about the project
filebrowser.info   Module metafile
filebrowser.module Module source code

Multiple descriptions for a file are concatenated into one. You can also
have help for a folder, (which is displayed as Drupal help text) with
the special dot mark (which means the description for the current folder):

. This folder contains the sourcode and some simple documentation
. for the filebrowser module, which was developed for the
. Hungarian Drupal Homepage to help
. users browse among our translations.

HTML is also free to use in descriptions. This can be a problem if you
allow those to edit the descriptions, who don't know HTML well.

You can have custom formatted descriptions in a file, in case you provide
a callback to process the descriptions in the metafile itself. This allows
you to use any number of differently formatted files in your filebrowser
repository. Use the special *callback* name (asterisks included) to
specify the function name:

*callback* docstate_description_parser
README.txt Detailed information about the project | DRAFT

Notice the extended description. If the function provided is not found,
then the complete text will end up in the description. If the function
is found however, then it is used to get the table headers printed after
the filename and size (including the description), and the data printed
for each file. This function can be defined anywhere, but it needs to 
be available to Drupal, when the file descriptions are parsed. An
example:

function docstate_description_parser($description = NULL, $subfolder = '', $filename = '') {
  // Handle query to return the headers for the table
  if (!isset($description)) {
    return array(
      t('Description'), // field 4, not sortable
      array('data' => t('State'), 'field' => 5) // sortable
    );
  }
  
  // Not a custom description (eg. description for a file which can have no state)
  if (strpos($description, '|') === FALSE) {
    return array(
      $description,
      array('data' => '', 'sv' => -1) // -1 as sort value
    );
  }
  
  // Parse the custom description format
  list ($desc, $state) = array_map("trim", explode("|", $description));
  return array(
    $desc,
    array('data' => $state, 'sv' => $state) // these can be sorted by state
  );
}

Note that what you return are basic Drupal table row segments, which are
added up to the default columns provided by the module. The headers specify
the binding between the table headers and the fields used for ordering - if
ordering is desired. Here we need no ordering for description, but do provide
ordering for the state field. Then the 'sv' is the sort value, by which the
sort is performed. -1 makes the item go to the top in ascending sort and
to the bottom in descending short. This callback is invoked for every
description, so it is important to handle the regular descriptions, which
are used for some files even if descriptions for other files are custom
formatted. The first three fields provided by the module are the name,
size and last modified values, so custom field numbering starts from 4.

Credits / Contact
------------------------------------------------------------------------------

This module was created for the Hungarian Drupal Homepage as a browser
for our local Subversion repository, where we work on the interface
translations. The author of the module is Gabor Hojtsy (gabor[at]hojtsy.hu).