
This box allows the browsing of a folder. It displays a list of
subfolders and files that are contained in the folder. It also
allows the user to browse the subfolders, to go to the parent folder,
to select a file, etc. The files that are displayed are those that 
match a certain filter specified by the programmer.


The variables
-------------
The 'folderListing' box uses some state variables to keep its
state. Some of these variables can be changed or can be used by the
box (or application) that contains this web box. These variables are:

* folderListing->root
  Contains the root folder. Should be initialized by the application
  the first time that the web box is rendered, and can be changed by
  the application at any time.
  
* folderListing->fileFilter
  Contains an ereg expression that is used to filter the files that
  are displayed. Should be initialized by the application the first
  time that the web box is rendered. If it is not initialized by the
  application, then it has a default value of ".*" (filter nothing).

* folderListing->currentPath
  Contains the path from the root to the current folder.
  
* folderListing->selectedFile
  Contains the name of the last file that was selected (clicked).
  

The events
----------
The 'folderListing' box raises some events and handles them internally.
These events can be used as well by the box or the application that
contains the 'folderListing'. These events are:

* folderListing.folder(folder_name)
  Raised when a folder is clicked. 
  The box handles this by displaying the selected folder.
  
* folderListing.up()
  Raised when the link to the parent folder is clicked. 
  The box displays the parent folder.

* folderListing.file(file_name)
  Raised when a file is clicked. 
  The box doesn't change its view.
  
* folderListing.root()
  Raised when the link to the root folder is clicked. 
  The box displays the root folder.
  
* folderListing.path(path)
  Raised when the sensitive path is clicked.
  The box displays the selected folder.
  
* folderListing.changeRoot(root_folder)
  Raised from outside the box (from the application that uses it).
  The box changes the root folder and displays it.
  
  
How to Use this Box
-------------------
Usually it can be used by including this line in the template that
contains it:

    <Include SRC="{{FOLDERLISTING_PATH}}folderListing.html" />  
    ({{FOLDERLISTING_PATH}} is declared by the framework itself)

In case that you want to change the layout of the webbox, then
you should copy the folder 'web_app/boxes/folderListing' from
the framework to some place in your application, then make changes 
to it and include it like this:

    <Include SRC="{{folderListing_path}}folderListing.html" />
    ({{folderListing_path}} must be declared by your application)

To change the layout of the webbox you can change the file 
'folderListing.html' and the file 'folderListing.css'.
