User Tools
Sidebar
This is an old revision of the document!
File List Plugin
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.
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/1), 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, 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
{{filename>:wiki:pluginsytnax:filelist*}}
turns into
:wiki:pluginsytnax:filelist:*
filelist
Example 1
{{filelist>:datasheets:*.pdf&style=table&tableheader=1&tableshowdate=1&tableshowsize=1&limit=15}}
turns into
:datasheets:*.pdf&style=table&tableheader=1&tableshowdate=1&tableshowsize=1&limit=15
Example 2
{{filelist>lib/images/*&style=list&direct=1}}
turns into
lib/images/*&style=list&direct=1&limit=15
Example 3
{{filelist>lib/images/*&style=olist&direct=1&recursive=1&sort=iname}}
turns into
lib/images/*&style=olist&direct=1&recursive=1&sort=iname&limit=30
Page Tools
Copyright © Alan Shea, 2011-2025