Filelist Plugin
Description
The filelist plugin provides a syntax for adding linked and sorted lists of files as selected by wildcard based glob patterns to a wiki page and thus allows dynamically including file listings of arbitrary filesystem locations and media namespaces. Using the additional filename command, one can also add a single link to a file out of a list anywhere in the text, which can be used to automatically keep download links for software releases up to date with the most recent upload.
In case you come across any bugs in this plugin, don't hesitate to report them.
The Darcs repository of the plugin can be found here.
Updates
Last updated: 2008/04/04
- 2008/04/04:
- Now respects ACLs in media mode and file permissions in direct mode. Files need to be readable in order to be displayed.
Users of Dokuwiki version up to 2007-06-26b: With the release of Dokuwiki version 2007-05-05, the date format got changed1). The filelist plugin incorporates this change, thus dates will not be displayed properly on versions below 2008-05-05.
- 2008/03/13:
- Should fix 24
- 2008/03/02:
- Implements 23 (
filelistoutput is now enclosed in an additionaldivwith classfilelist-pluginwhich can be used to apply specific css to anything contained inside)
- 2008/01/24:
- (Hopefully
) fixes 19 - tested with Linux only as I currently have no access to a Windows-box, so Windows-users please give feedback!
- 2007/11/05:
- Initial release
Acknowledgements
Based on an idea by demod.
Installation
With plugin manager
Let the manager do the dirty work, just give him this link to eat: plugin-filelist.tar.gz
Without plugin manager
- Download the plugin: plugin-filelist.tar.gz
- Extract it into your dokuwiki plugin folder (eg
lib/plugins)
Configuration
The filelist plugin has three configurable options:
| Option | Description |
|---|---|
allow_in_comments | Whether to allow the usage of the filelist/filename syntax in comments by the discussion plugin. Defaults to 0 and thus prohibition of the plugin usage in this scenario. |
allowed_absolute_paths | A comma-separated whitelist of all paths beneath which to allow the scanning using the filelist/filename syntax. Defaults to the Dokuwiki basedir DOKU_INC. |
web_paths | A comma-separated list of URLs via which the previously defined absolut paths are reachable to wiki users. This list MUST contain exactly the same amount of entries as allowed_absolute_paths. Defaults to the Dokuwiki base-URL DOKU_URL as a mapping for DOKU_INC. |
Usage
The filelist plugin provides two new commands to be used in wiki pages, filelist and filename. The general command syntax for both is the following:
{{[ command ]>[ pattern ][ parameterlist ]}}
- command must be either
filelistorfilename. - pattern is a searching pattern for files to include in the generated list, defined using the pattern syntax of the unix fnmatch function. An example: If you want to include all files ending on
.txtin the foldersome/path/2), you would usesome/path/*.txtas the pattern (and the parameterdirect=1, see parameters below). Analogue to this, to include all jpeg media files in:some:namespace, you'd use:some:namespace:*.jpg. - parameterlist can be used to define optional,
&separated parameters (defined as key-value-pairs). For a list of supported parameters, see below.
Paths
The filelist plugin supports both absolute as well as relative paths into the filesystem or Dokuwiki media namespaces. All paths are checked against a whitelist of allowed paths for scanning (as defined via the configuration setting ''allowed_absolute_paths''). Paths which are not located below these whitelisted paths are not allowed for globbing and thus filelist/filename calls to such paths fail. Per default, the Dokuwiki basedir as defined in DOKU_INC is included in this whitelist and mapped to the Dokuwiki base-URL, DOKU_URL.
Relative paths into the filesystem are interpreted relative to the Dokuwiki basedir. Relative media paths (without a leading : that is) are interpreted relative to the namespace of the currently active page. Thus, :snippets:dokuwiki:* and * would be interpreted the same on the current page :snippets:dokuwiki:filelist.
Parameters
| Name | Description | Possible values | Default |
|---|---|---|---|
direct | Whether to interpret the given pattern as a direct path in the file system or as an dokuwiki media id. Defaults to media id. | 0 or 1 | 0 |
sort | The property by which to sort the internal file list. By default, the file name is used. | name, ctime, mtime, size | name |
order | Whether to sort the internal file list ascending or descending. Sorting in ascending order is the default. | asc, desc | asc |
filelist specific parameters | |||
offset | The offset in the internal file list from which on to display the list. Default is an offset of 0. | any numeric value | 0 |
limit | The number of files to display, beginning at index offset. A number of 0 means to display all available files. | any numeric value | 0 |
style | The style to use for display. list creates an unordered bullet list (the default), olist an ordered list and table a table view of the selected files. | list, olist, table | list |
tableheader | Whether to show the table header describing the table columns. Off by default. | 0 or 1 | 0 |
tableshowdate | Whether to show the file modification date in the table view. Off by default. | 0 or 1 | 0 |
tableshowsize | Whether to show the file size in the table view. Off by default. | 0 or 1 | 0 |
filename specific parameters | |||
| index | Which specific item to select for display from the internal file list. The default is the first one. | any numeric value | 0 |
Examples
filename
filelist
Example 1
{{filelist>:snippets:dokuwiki:plugin-*.tar.gz&style=table&tableheader=1&tableshowdate=1&tableshowsize=1}}
turns into
| Filename | Filesize | Last modified |
|---|---|---|
| plugin-blockquote.tar.gz | 13101 | 2008/05/04 11:19 |
| plugin-bloglinks.tar.gz | 10060 | 2008/07/07 21:07 |
| plugin-filelist.tar.gz | 4728 | 2008/05/21 15:23 |
| plugin-keyboard.tar.gz | 10346 | 2008/05/04 11:51 |
| plugin-linkback.tar.gz | 22676 | 2008/04/06 11:20 |
Example 2
{{filelist>lib/images/*&style=list&direct=1}}
turns into
Discussion
Very cool plugin !!
Very useful! Now I can link lots of files in my wiki without the hassle to keep them up-to-date. —<(kaimartin)>—
I get this error message when using your plugin:
Warning: Call-time pass-by-reference has been deprecated; If you would like to pass it by reference, modify the declaration of [runtime function name](). If you would like to enable call-time pass-by-reference, you can set allow_call_time_pass_reference to true in your INI file. in C:\Inetpub\wwwroot\lib\plugins\filelist\syntax.php on line 135
As already indicated at 24, this should now be fixed.
Thanks for the nice plugin. I was hoping to use to list files on a windows share, can it do that? I was using the usual DokuWiki linking syntax for that, e.g. {{filelist>\\server\dir1\dir2\*&direct=1}}
but got [n/a: Access denied]
I did add the “\\server\dir1” path to the list of allowed path and also added an entry in the URL paths (although I do not understand the meaning of that second path). Any ideas?
I don't have a development system under windows available, and no windows shares, but I'll do my best to fix this anyways – might find some suitable test environment at work with luck, or victim to test stuff out. Please open a bugreport in the bugtracker though, so that the problem has no chance to disappear from my radar. Thanks in advance.
I moved my data directory out of the wiki installation for security reasons, and the plugin no longer finds those files when configured for media access.
I've traced this to line 31 of syntax.php, which probably needs to be changed to check if the $conf['savedir'] is an absolute path, and if so, not prepend the DOKU_INC path prefix.
Could you please open a bug in the bugtracker for this issue? Thanks in advance.