• View
• Edit
• History
• Attach
• Print
• Backlinks

DirList

Description

Local/LAN directory listings and downloads.

The recipe lists a directory on the server or a shared LAN folder. It allows wiki visitors to browse into sub-directories and to download files. The listing is read-only, users cannot add, change or delete files. File and directory filters offer good control about what gets listed.

The recipe offers also a workaround for the problem that browsers refuse to follow file:// links.

Demo.

The recipe was written for an intranet wiki where all users could browse a shared folder "Software" and install programs on their own computers.

Installation

• Copy the file dirlist.phpΔ to your cookbook directory. (Alt. download: dirlist.php.)
• Add to local/config.php or to a group configuration file such a line:
  include_once("$FarmD/cookbook/dirlist.php");

Configuration

An administrator can set a small number of configuration variables in config.php.

• $DirList['Root'] = "C:/path/to/root/dir";
  (no trailing slash) The path to the root directory. Visitors will be able to browse sub-directories and download all files from the root directory, but will have no access outside of it.
  To list a shared folder on your LAN, use "\\\\MYSHARE/folder" . Note that you need 4 slashes instead of 2, and note that you cannot list the full share itself, you need to select a folder in it.
• $DirList['parent'] = "Go to parent directory";
  The text of the link to go back on the directory tree. Default is "..".
• $DirList['defaultfilter'] = "-*~,-*.bak";
  The default filter controlling which files should be or shouldn't be listed. In the above example, files ending with a ~tilde or with a .bak extension will not be shown. This can be overriden in the wiki page.
• $DirList['TimeFmt'] = "%Y-%m-%d";
  The date and time format used in the file listings (default $TimeFmt).
• $DirList['EncodeFn'] = "YourEncodeFunction";
  a function used to encode the url address of a file or directory, defaults to the standard 'rawurlencode'. If you need a different function, write its name here. If you need no encoding at all, use here "IsEnabled" (note that in some cases this may be non-standard).
• $DirList['NFormatFn'] = "YourNumberFormatFunction";
  a function used to format the file sizes. By default, files are shown in a "friendly" format, in bytes, kibibytes, mebibytes or gibibytes with an appended suffix (k, M or G). If you require a formatting by another function, place its name here.

Usage

In a wiki page, the markup is (:dirlist [optional ChildDirectory] [optional parameters]:)

Child directory

• (:dirlist:) without a child directory will list the files at {your Root}/.
• (:dirlist Documents/Texts:) will list the folder {your Root}/Documents/Texts.

Optional parameters

• nodirs=1 do not list directories.
• nofiles=1 do not list files.
• nodefaultfilter=1 ignore the default filter specified in config.php.
• dirfilter="[ABCD]*,-Backup*" list only directories starting with "A", "B", "C" or "D", except those starting with "Backup".
• filter="*.odt,*.doc,*.txt" list only files with the extensions .odt, .doc and .txt.

Note about ChildDirectories and filters. The program can potentially deliver any file from the Root directory. Filters control what is shown in the listings, but if a user guesses a file name and constructs a special URL, this file could be downloaded.

For this reason, make sure you don't have confidential files in your Root directory. (Downloading files does require read permissions for the wiki page.)

Additional "File:" InterMap shortcut

The recipe allows you to create a custom InterMap shortcut and to more easily link to local files. For example, you could map the "File:" prefix in your page Site.InterMap:

  File:   http://your-wiki/Group/DirList?action=dirlistget&f=

(Group/DirList is a page where the recipe is enabled.)

Then, you can link to files in your Root directory like this:

  [[File:text.odt | click here ]] to link to {Root}/text.odt
  File:Pictures/image.jpg to embed the image {Root}/Pictures/image.jpg

Of course, you can select a different InterMap prefix.

Notes

• If you use more than one (:dirlist:) markup in the same page, you can browse sub-folders in only one dirlist at the same time. Or you can use the parameter nodirs=1 in all dirlists.
• Don't place confidential files in your $DirList['Root'] directory.
• Your webserver (or the PHP process) needs "read" ("+r") permissions for the Root directory and for the files inside it.
• Your webserver (or the PHP process) needs "read" ("+r") and "scan/list" ("+x") permissions for the Root directory and all subdirectories.
• The recipe uses scripts/uploads.php, so if you need to disable uploads, set in config.php such a line:
  $UploadMaxSize = 0;

Change log / Release notes

• 20241030 Update for PHP 8.3, requires PmWiki 2.3.1 or more recent. Made compatible with $EnableSortable (added row headers, data-sort attributes), $EnableLocalTimes (modified variable 'TimeFmt'), and Filterable. The table now has the additional class name "simpletable" which should reuse the styles of the skin or the wiki. The number formatting now uses the core function FileSizeCompact() rather than a custom one.
• 20200318 Update for PHP 7.2 and 7.4.
• 20150405 Fixes for PHP 5.5. The recipe now requires PmWiki 2.2.58 or more recent.
• 20130206 Add variables TimeFmt, EncodeFn, NFormatFn.
• 20110118 First public release, ready to be tested.

See also

Contributors

• The recipe is written and maintained by Petko (5ko [snail] 5ko [period] fr). Parts of the code were inspired by functions in upload.php by Pm.
• If this recipe helps you or saves you time, you can help support its continued development by ♥ .

Comments

See discussion at DirList-Talk