Class
Class
Mode
Enabled
| CleanCode Perl Libraries |
| Home | Perl | Java | PowerShell | C# | SQL | Index | Tools | Download | What's New |
| Multi-Lingual Library | Maintainability | ||||||||||||
|
Perl | |
Java | |
JavaScript | |
Certified Class |
|
Testable Class |
|
Standalone Mode |
|
Diagnostic Enabled |
list - List a directory as a web page, textually or graphically.
list [ options ]
Specifies the project ID to display, which is used as a key to the configuration file to obtain specs for the project.
Specifies the directory within the project to display as the current directory.
Specifies the name of a column to use as the sort key for list view. Note that this is not the display name for the column, but rather the internal name in the column, which is specified as the name field in the @COLS list.
Specifies the direction of sort for the current sort column. A true value will sort ascending, a false value, descending.
Specifies program mode: list (shows current directory with subdirectory names first), listflat (shows current directory with subdirectory details inline), imglist (shows current directory with subdirectories, then image previews, then non-image files), img (an image-only view), tree (shows all nested directories), or faq (the faq page).
With an "all" value forgets that the user ever visited. With a "now" value, does not record the current visit.
CGI, CGI::Carp, File::stat, User::pwent, User::grent, HTML::Template, XML::DOM, CGI::Handy, File::Handy, Data::Handy, XML::DocumentPlus
This program is a simple file manager to provide web access to a directory. The display of a directory depends upon the program mode. The modes are specified via the mode parameter given above; see subsequent sections for how to customize the display.
A directory listing, showing the contents of a single directory, akin to a standard Unix directory listing, with a couple enhancements. Each plain file shows name, owner, group, last modified date, and permissions, plus an icon representing the file type. Sub-directories, on the other hand, are listed with just a folder icon and a name, and are listed first. Both files and sub-directories include a hyperlink to access the item. Any given directory may have either files, subdirectories, both, or neither.
The listflat mode is a variation of the ordinary list view; this displays sub-directories inline with full details, just like plain files.
The imglist mode is another variation that starts with the ordinary list view (subdirectory names first, then file details). However, any image files are shown as thumbnail previews rather than being in the file list.
A hirerarchical directory listing, showing the contents of a directory and all of its descendants. Both files and subdirectories display the same information, an icon and a name, with a hyperlink to access the item. Each nested subdirectory is indented to display the hierarchy. The tree view shows hierarchy for the current directory and its descendants. Thus, from the starting directory, this will display the entire hierarchy, but invoked from a lower directory, it will show a smaller branch of the tree.
A graphical listing, displaying an image and a name for each entry. This will only be a useful listing if you have set up the contents of your directory appropriately. For each document file to be listed you must have a correspondingly named image file. For example, if you have a document file file.xyz then you must also have an image file file.xyz.jpg (or .jpeg or .gif or .png) in the same directory. Any file without a corresponding image file will be silently ignored.
A dynamically generated FAQ page, which describes basic operations of the file manager for both users and project administrators. This FAQ page includes a list of all known file types, which is generated dynamically, so when new ones are added to the icon directory, they will automatically show up on the FAQ page. (The table of contents at the top of the page is also generated dynamically, so that as new questions are added, they will automatically be indexed.)
When invoked, one provides a project identifier which is used as a key into the project list specifications in the configuration file. The project configuration file must be called list.xml and stored in the same directory as the program itself. All other support files may be located where you please, as you specify the location in the configuration file.
The configuration file contains global definitions, (such as the location of the support files), project-specific definitions (such as the display name of a project), and some definitions which may be specified globally as a default, but then overridden at the project level if desired (such as the administrator e-mail address).
Global; One of the project identifiers defined in the same file.
Global; Web path to the directory containing the support files needed by this program. Must resolve to the same location as supportDirFile.
Global; Filesystem path to the directory containing the support files needed by this program. Must resolve to the same location as supportDirWeb.
Global; Web path to the directory containing the image files needed by this program. Must resolve to the same location as imageDirFile.
Global; Filesystem path to the directory containing the image files needed by this program. Must resolve to the same location as imageDirWeb.
Global or project; Email address of the default administrator for this program. If specified locally, will override the global value.
Project: Identifier for the project, selected via the proj command-line parameter.
Project; Web path to the root directory for the containing project. Must resolve to the same location as fileRoot.
Project; Filesystem path to the root directory for the containing project. Must resolve to the same location as webRoot.
Project; Display name for this project.
Project; Boolean indicating to use graphical view or not.
Project; Specifies the direction of sort for the current sort column. A true value will sort ascending, a false value, descending. This is the starting default for the project; it may be overridden from client interactions.
The listing generated by this program is delivered to the client browser as XML (for the tree view) or HTML for all others (list view, faq, etc.). These pages are generated from templates, an XSL template for the tree view, an HTML::Template type for the others. These templates, along with other support files, are stored in a directory specified in the configuration file (the doc/supportDirWeb and doc/supportDirFile parameters). The list below specifies the template file used for each file mode.
list.xsl
template.html
template-img.html
template-faq.html
These templates are global to all projects, so any customization applies to all projects. There is, however, some flexibility to customize on a per-project basis as follows.
The files .header.htm and .footer.htm, placed in your project's root directory, allow you to customize all pages within your project. As one might infer, the contents of .header.htm go near the top of the web page; the contents of .footer.htm go near the bottom. Besides this project-level customization, you may further customize on a directory-by-directory basis within your project. Place a file named .directory.htm in any directory you choose; the contents of this file, if present, will immediately follow the contents of .header.htm.
Note that various fatal initialization errors will generate a simple error output, bypassing the templates. This includes: a project ID not found, a specified subdirectory not found, non-wellformed XML in the configuration file, key nodes missing from the configuration file, and so forth.
Images are stored in a directory specified in the configuration file (the doc/imageDirWeb and doc/imageDirFile parameters). Beneath this directory, there are two subdirectories, for file icons ("icons") and for web buttons ("buttons"). The file icons are used to graphically display the type of each file in a list view or tree view, whether it be an Excel file, an HTML file, a plain text file, a folder, etc. If a file has an extension which is not in the icon library, a question-mark graphic is displayed indicating unknown type.
Occasional reports of tree mode failure have me stumped; the browser just displays the text of the xml rather than processing it through the xsl template. The msxml and browser versions both seem to work in other circumstances, so I've not been able to isolate what is different.
Michael Sorens
$Revision: 1356 $ $Date: 2013-03-17 22:08:33 -0700 (Sun, 17 Mar 2013) $
CleanCode 0.9
| Home | Perl | Java | PowerShell | C# | SQL | Index | Tools | Download | What's New |
| CleanCode Perl Libraries | Copyright © 2001-2013 Michael Sorens - Revised 2013.06.30 |