======File List Plugin====

The [[http://www.foosel.org/snippets/dokuwiki/filelist|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. 

===== 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, with upper case being sorted before lower case (use ''iname'' for a case insensitive sorting criteria). | ''name'', ''iname'', ''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, ''table'' a table view and ''page'' a heading/section based view of the selected files. | ''list'', ''olist'', ''table'', ''page'' | ''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'' |
| ''recursive'' | Whether to do a recursive file crawl starting at the defined basepath. If this parameter is set to ''1'', the whitecard part of the search pattern is applied to each found subdirectory. If no files are found, the subdirectory is not included in the search result. All display styles besides ''table'' will show the result in a hierarchical structure; ''table'' will first flatten the result by prepending all found files with there subtree pathname (note that this happens before sorting). | ''0'' or ''1'' | ''0'' |
| ''titlefile'' | The filename of a file which to lookup in each subtree if ''recursive'' is set to ''1'' and whose content to use as title for the directory. It will be ignored in the results of the filelisting itself. Defaults to ''_title.txt''. Example: A ''_title.txt'' file containing "My special title" found during a crawl on the subpath ''my/subpath'' will be rendered as having the name "My special title" instead of "subpath". | any filename | ''_title.txt'' |
^ ^ ''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>:cp:c61-genset-control-tower-3p.jpg}}</code>

turns into

{{filename>:cp:c61-genset-control-tower-3p.jpg}}
\\ \\

==== filelist ===

== Example 1 ==

<code>{{filelist>:datasheets:*.pdf&style=table&tableheader=1&tableshowdate=1&tableshowsize=1&limit=15}}</code>

turns into

{{filelist>:datasheets:*.pdf&style=table&tableheader=1&tableshowdate=1&tableshowsize=1&limit=15}}

== Example 2 ==

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

turns into 

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

== Example 3 ==

<code>{{filelist>lib/images/*&style=olist&direct=1&recursive=1&sort=iname}}</code>

turns into

{{filelist>lib/images/*&style=olist&direct=1&recursive=1&sort=iname&limit=30}}