$Id: README.txt,v 1.5 2006/03/26 13:53:57 goba Exp $

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
metafiles (CVS and .svn folders) 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.module to your Drupal modules folder
  - Enable the module as usual on Drupal's admin page
  - Provide the module settings on the administration >> settings >> 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 if you have menu module turned
    on, 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 though 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.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
. <a href="http://drupal.hu">Hungarian Drupal Homepage</a> 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:
<pre>
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
  );
}
</pre>
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.


Using Filebrowser as a widget in other contexts
------------------------------------------------------------------------------
Inline
---------------------------------------
The filebrowser renderer can be used embedded in other pages, or stand-alone.

To EMBED a filebrowser table, the following PHP snippet could be copied into 
a (php code) node:

	<?php
	$folder = 'imported';
	print filebrowser_page($folder);
	?>

This is useful for providing direct access to a download directory, but is only 
the default rendering, and doesn't behave with subdirectories.

A slightly more advanced version lets you select which columns to show. 

<?php
  $subfolder = 'imported';
  $cols = array('icon','file'); // also used as headers. (no tablesort)
  $files = filebrowser_get_list($subfolder, $cols);
  print theme('filebrowser_page', $files, $cols);
?>

Handling deep browsing to folders is trickier, and best done as a custom 
callback, not a PHP snippet, but the AJAX expanders can be told to work. 
The 'filebrowser_contexts' parameter has to be set so the request knows what
columns to display later.

<?php
  $subfolder = '';

  // very simple list
  $cols = array('expander','file'); 
  
  $context = "demo";
  // set context
  filebrowser_proper_path('', $context);

  // Memo this column layout as a message to child AJAX requests
  filebrowser_set_context($context, $cols);
    
  $files = filebrowser_get_list($subfolder, $cols);
  if(is_array($files)){
	  array_shift($files); // no parent link
	}
  print theme('filebrowser_page', $files);
?>
---------------------------------------
Custom columns
---------------------------------------
Available columns are :
expander : AJAX callback trigger to expand directories
name     : linked filename, directorys linked to callback (sortable)
file     : linked filename, directories NOT linked (use when embedding)
icon     : linked icon
age      : formatted duration (sortable)
size     : formatted size (sortable)
type     : suffix (sortable)
info     : description, extracted as described above

More can be added by custom modules! Then invoked from other contexts.
See the filebrowser_get_cell_hook() examples in the code.

---------------------------------------
Popup
---------------------------------------
Filebrowser can now be used as a standalone popup widget.
The following code will launch a small filebrowser window, which will send back
the path of the selected file to the named form element.
<pre>
  <form>
    <input type=text id='fillme'/>
    <input type='button' value='browse files' onclick='goBrowse()' />
    <script>  
      function goBrowse(){
        window.open(
        "<?php echo url("filebrowser_popup" ,"targetelement=fillme"); ?>",
        "popup", 
        "width=400, height=600, resizable=yes"
        )
      }
    </script>
  </form>
</pre>
---------------------------------------
Autocomplete
---------------------------------------
Also, an autocomplete handler is available. Creating a form element:
<?php
   $form["choose_file"] = array(
  	'#type' => 'textfield',
  	'#title' => t("File"),
  	'#autocomplete_path' 	 	 => 'filebrowser/autocomplete',
 	);

 	print(drupal_get_form('demo',$form));
?>
 ... will help you fill in the gaps.

Extending the	'#autocomplete_path' , eg:
'filebrowser/autocomplete/avatars' 
would start the completion from below that directory.
(browsing is always limited to below the system 'files' directory, so paths 
begin relative to that) 

Autocomplete in subdirectories requires a bugfix in form.inc 4.7.2
http://drupal.org/node/52116#comment-116656 
 
For extreme examples, see the attach.module.


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 (goba[at]php.net).

Extended and reworked by dman (dan[at]coders.co.nz) to add AJAX functionality,
column selection, autocomplete and pop-up widget.