====== 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 [[http://flyspray.foosel.net/index.php?do=newtask&project=10|report them]].

The Darcs repository of the plugin can be found [[http://devel.foosel.org/darcsweb/darcsweb.cgi?r=dokuwiki/filelist;a=summary|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 changed((use of ''strftime'' instead of ''date'' on ''$conf['dformat']'')). The filelist plugin incorporates this change, thus dates will not be displayed properly on versions below 2008-05-05.
  * 2008/03/13:
    * Should fix [[bug>24]]
  * 2008/03/02:
    * Fixes [[bug>21]], [[bug>22]]
    * Implements [[bug>23]] (''filelist'' output is now enclosed in an additional ''div'' with class ''filelist-plugin'' which can be used to apply specific css to anything contained inside)
  * 2008/01/24:
    * (Hopefully ;-)) fixes [[bug>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 [[http://demod.org|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 [[http://wiki.splitbrain.org/plugin:discussion|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:
<code>
{{[ command ]>[ pattern ][ parameterlist ]}}
</code>

  * **command** must be either ''filelist'' or ''filename''.
  * **pattern** is a searching pattern for files to include in the generated list, defined using the [[http://man.cx/fnmatch(7)|pattern syntax of the unix fnmatch function]]. An example: If you want to include all files ending on ''.txt'' in the folder ''some/path/''((relative to your dokuwiki root)), you would use ''some/path/*.txt'' as the pattern (and the parameter ''direct=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 [[#parameters|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|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 ===

<code>{{filename>:snippets:dokuwiki:*filelist*}}</code>

turns into

{{filename>:snippets:dokuwiki:*filelist*}}

=== filelist ===

== Example 1 ==

<code>{{filelist>:snippets:dokuwiki:plugin-*.tar.gz&style=table&tableheader=1&tableshowdate=1&tableshowsize=1}}</code>

turns into

{{filelist>:snippets:dokuwiki:plugin-*.tar.gz&style=table&tableheader=1&tableshowdate=1&tableshowsize=1}}

== Example 2 ==

<code>{{filelist>lib/images/*&style=list&direct=1}}</code>

turns into 

{{filelist>lib/images/*&style=list&direct=1}}

~~DISCUSSION~~