Provides a syntax for adding linked and sorted lists of files as selected by wildcard based glob patterns to a wiki page
Compatible with DokuWiki
Provides a syntax for adding linked and sorted lists of files as selected by wildcard based glob patterns to a wiki page
Update to 2024-02-27 breaks backwards compatibility, read docs before upgrading
Similar to directorylist, filelisting, medialist
Needed for doctree2filelist
The filelist plugin provides a syntax for creating linked listings of arbitrary file system locations. It is meant to add easy access to file server shares and similar document stores.
Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.
Release 2024-02-27 is a complete refactoring of the old plugin. The following features have been removed:
If you accidentally updated and need to revert back to the previous release, refer to tag 2020-09-27.
Path configuration differs from previous releases. Please see below to set up your paths again.
Some more info is available in the pull request.
To use this plugin, you need to configure one or more paths that should be allowed for listings.
These paths need to be available on the same server your wiki is running on. This can be a local directory, a file system mount or a UNC path to a file share (Windows only).
All files and directories below the configured paths will be available to the plugin for listing. The PHP process running your DokuWiki needs to be allowed to read these files and directories!
Note: in older plugin versions the paths were configured in theallowed_absolute_paths
config option.
For each configured path an optional alias may be configured. This alias will simplify the syntax when using the plugin (see examples below).
For each configured path you may configure how the listed files are to be accessed via the web. Eg. how the full URL to download a file is to be constructed. By default files will be delivered by DokuWiki itself, without any additional permission checks - if PHP can read the file, a user may download it. By configuring your own web prefix, you can implement your own mechanism of file delivery.
For example custom web prefixes could be used for using your web server to deliver the files without involving PHP or to redirect all links to a document management system.
Note: in older plugin versions the web prefixes were configured in theweb_paths
config option.
All the above things are configured in the paths
configuration (using the Configuration Manager). The setting is line based, with each path, alias and web prefix on their own line. Aliases and web prefixes have to follow the path they belong to and are prefixed by A>
and W>
respectively. Leading and trailing white space is ignored.
Example
\\somewindows.server\with\a\share W> https://somewindows.server/has/itsowndocroot/ A> fileserver /this/is/a/local/path/outside/thewebroot/ A> local
Forward or backward slashes are mostly interchangeable. Only UNC paths have to start with two backslashes.
Important: the plugin will never list or give access to files in the DokuWiki or data directories, regardless of the path configuration. This would circumvent ACL checking and compromise the security of the wiki.
There are a few more options you can set in the Configuration Manager.
allow_in_comments
Whether to allow the usage of the filelist syntax in comments by the discussion plugin. Defaults to 0
and thus prohibits the plugin usage in this scenario.defaults
Syntax defaults that should always apply to all syntax invokes. See usage section for details.extensions
A comma-separated list of file extensions the plugin should be restricted to. If there is a list configured here, only files with these extensions will be listed. Empty allows all files.The filelist plugin provides a new syntax to list files. The general command syntax is the following:
{{filelist>[ pattern ][ parameterlist ]}}
The pattern defines what files to list. It uses the pattern syntax of the unix fnmatch function. It has to start with a path or alias defined in the configuration.
For example, with the example path configuration from above, the following would list all files ending on .txt
in the file server directory foo
:
{{filelist>fileserver/foo/*.txt}}
The parameterlist can be used to define optional, &
separated parameters (defined as key-value-pairs). These parameters influence how files are found, displayed and sorted. For a list of supported parameters, see below.
Name | Description | Possible values | Default |
---|---|---|---|
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 |
cache | Whether to disable or enable caching for the page. Default is no caching. | 0 or 1 | 0 |
style | The style to use for display. list creates an unordered bullet list (the default), olist an ordered list, table a table view | list ,olist ,table | list |
tableheader | Whether to show the table header describing the table columns. Off by default. | 0 or 1 | 0 |
showdate | Whether to show the file modification date in the table view. Works with all style options. Off by default. | 0 or 1 | 0 |
showsize | Whether to show the file size in the table view. Works with all style options. 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 wildcard 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 |
randlinks | Whether to generate random links with timestamps to prevent linked-to files from being cached by the browser. Off by default. | 0 or 1 | 0 |
listsep | List separator to use between the fields (e.g. “linktext, showsize”). Default is , . | Any character sequence | , |