27 May 2017
vuDir.php : a directory viewer, with file deletion capabilities
vuDir.php is a php script that display directory information on a selected directory.
Its features include
* Multi column display of information on each file (and subdirectory) in a directory: name, extension, size, and creation date.
* Little icons (depending on the extension) are also displayed
* You can sort on any of these columns
* Delete buttons can be added to the listing (for one-at-a-time file deletion)
* Subdirectories, and hidden files (that begin with a ".") can be optionally displayed
* Files can be downloaded to the browser, or to a file
* Special support for wsEmail file name syntax.
* Several access controls: a .vuDir method, and (indirectly) .htaccess
Installation:
The vuDir directory should be installed under the /wsurvey/ directory.
Useage
There are two steps:
1) Include on your desired web page a link that displays the desired directory.
The basic syntax is
/wsurvey/vuDir/vuDir.php?dir=aDirectory
aDirectory can be either relative or absolute (beginning with a /)
* If relative, will be relative to the page containing the link (assuming the browswer sent a "Referer" header)
* If not relative (or if no "Referer" header), the directory is relative to the root of the web tree (for this server)
* Directly entering a url (such as /wsurvey/vuDir/vuDir.php?dir=aDirectory) in a browsers url line means there will NOT be a "Referer" header -- so
one should use "absolute" reference
Examples:
If /personal/joe/index.htm contains this link:
View my stuff in new window
then clicking on it will display the contents of (since the "Referer" points to /personal/joe/):
/personal/joe/mystuff
If /personal/joe/index.htm contains this link:
VIew my stuff in new window
then clicking on it will display the contents of
/common/ourstuff
2) In ANY directory that is referenced by vuDir (an "aDirectory" directory) you MUST include a .vuDir file!
With one exception (described below), if there is no .vuDir file in a directory, then vuDir.php will issue an error message
if asked to display files in the directory.
This is a security precaution, that complements server access controls (such as in .htaccess files)
In addition: whenever vuDir.php tries to read a file, server access controls are ALWAYS checked.
When vuDir.php first lists directory contents, it can be subject to server access controls (given the value of the checkDirAccess parameters)
.vuDir is a simple file that can contain several variables:
Each line of a .vuDir file has a syntax of: varname=value
lines that begin with a # are comments; empty lines are ignored
The supported varnames, and values. Unless noted otherwise, varname and value are case insensitive. Also note that
where noted, you can use shorter synonyms for the varnames
allowAccess=0 : Default =1. If 0, do NOT allow vuDir.php to view this directory
(or ACCESS or ALLOW)
allowShowHidden=0 or 1 : Default=1. Allow hidden files to be shown. 0=no, 1= yes.
(or HIDDEN) If 0, then hidden files (that begin with a ".", such as .htaccess and .vuDir) are never displayed.
If 1, then a "show hidden files" link is displayed at the bottom of the file list.
allowDel=0 or 1 : Default=0. Allow vuDir to delete files. 0=no, 1=yes. If 1, "delete this file" links will be displayed
(or DEL) Files can be deleted one at a time.
allowView=0 or 1 : Default=1. Allow user to view the files (by clicking on them). If 0, files will be listed.
(or VIEW) This can be convenient when access is denied due to server controls (i.e.; due to an .htaccess file) -- otherwise,
users might get annoyed when they click on links and get access denied error messages.
checkDirAccess=0 or 1 : Default=0. If 1, check server access before listing files. This uses a request to /dir/ (i.e.; a
request to the directory's default).
(or CHECK or CHECKDIR) If 0, file listing will occur without checking server access control.
However: checkDirAccess never effects file viewing & downloading (which is always subject to server access controls)
message = a message : Default='A listing of files". Longer name for this page. pagename, then message, are displayed above the file menu
(the "a message" is not capitalized, and need NOT be "quoted")
parseNames=0 or 1 : Default=''. If not '', then should be comma delimited list of extensions.
(or PARSE or PARSENAME) Files with these extensions will have their names prettified (see below for the rules used for prettifying)>
Or, parsname=* : then prettify the names of all files (regardless of extension)
Example: parseName=wsEmail, mbx
Note: case-insensitive extensions are used (so mbx and MBx are the same)
pagename = a name : Default='Directory listing'. Short name for this page (the "a name" is not capitalized, and need NOT be "quoted")
(or NAME)
allowViewMessage = a message : Default='Sorry, file viewing not permitted '. When clicking on a file name (or other field), and when allowView=0,
this message will be displayed in an alert box (and NO file download is done).
showSubdirs=0,1, 2 : Default=1. Allow display of subdirectories. 0=No, 1=yes, 2=yes w/NO .vuDir check.
(or DIR) For 2, the .vuDir in this "parent" directory is used
This is the sole exception to "a .vuDir file must be in the directory".
It is a limited exception, as the .vuDir file MUST be in a parent (of a directory that does not contain a .vuDir)
Notes:
* the values of pagename and message are NOT capitalized
* vuDir.example contains an example of a .vuDir file
* parseName file name syntax
parseName is used to identify extensions. If a file has an extension that matches an extension in parsEName,
its name will be "prettified" -- it is seperated into formatted (some with mouse-over titles) components
These filenames should contain underscore ("_") characters in the name part of the filename. These seperate the filename into "fields".
The following rules are used to prettify :
* if zero or one _, nothing is done (the filename is not prettified)
* If two _ : name_subname_intdate
name : a "name" -- it will be displayed bolded (for example, the "wsEmail account")
subname : the "subname" -- it will be displayed in a lower case, small font (for example, the wsEmail in or out box)
intdate : unix style date (seconds from 1/1/1970). It will be displayed using format of (without the quotes): [mon dd yyy hr:mn]
Warning: on some systems, dates above 2148000000 will start at 1901!
Example: myacct_IN_1410872569 yields (the "myacct" is bolded, the "in" is monospaced)
myacct in [Sept 16 2014 13:02]
* If three _ : name_subname_ct_intdate_other
name : the "account" -- it will be displayed bolded
suname : the "box" -- it will be displayed in a lower case, small font
ct : a parenthetical noter -- it will be displayed after the "subname", in (parenthesis)
intdate : unix style date (seconds from 1/1/1970). It will be displayed using format of (without the quotes): [mon dd yyy hr:mn]
Example: hisacct_out_3264_1412825976 yields (the "hisacct" is bolded, the "out" and "3264" are small lower case)
hisacct in (3264) [Oct 27 2014 3:39]
* If four or more: name_subname_ct_intdate_other
name, subname, ct, and intdate are the same above.
other, which can contain _ characters, is displayed underlined
Example: ouracct_spam_all_1412697641_image_001 (the "image_001" will be underlined)
outacct spam (all) in [Oct 7 2014 16:00] image_001
Created by Daniel Hellerstein. danielh@crosslink.net.
Useage subject to the usual GPL licensing -- see gpl.txt in the /wsurevy/ directory.
Many components of vuDir are derived from a package from http://css-tricks.com/snippets/php/display-styled-directory-contents/
The slightly modified version of this package is in dirOne.zip (in the dirOne) directory. It can be used for one-directory
file listing, but it must be installed in every directory you want to list the files of.