====== filelist Plugin ======
---- plugin ----
description: Provides a syntax for adding linked and sorted lists of files as selected by wildcard based glob patterns to a wiki page
author : Dokufreaks (previous author: Gina Häußge)
email : freaks@dokuwiki.org
type : syntax
lastupdate : 2024-04-03
compatible : Jack Jackrum, Kaos
depends :
conflicts :
similar : medialist
tags : file, listing, download, filter, odt
updatemessage: Update to 2024-02-27 breaks backwards compatibility, read docs before upgrading
downloadurl: https://github.com/dokufreaks/plugin-filelist/archive/master.zip
bugtracker : https://github.com/dokufreaks/plugin-filelist/issues
sourcerepo : https://github.com/dokufreaks/plugin-filelist/
donationurl:
screenshot_img : https://github.com/dokufreaks/plugin-filelist/raw/master/FilelistScreenshot.png
----
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.
===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
==== Upgrade from older Versions ====
Release 2024-02-27 is a complete refactoring of the old plugin. The following features have been removed:
* all handling of media files including the various preview options
* This is better served by other plugins like the [[filelisting]] or [[gallery]] plugins
* output of single links
* page style output
* paging options (offset, limit, index)
If you accidentally updated and need to revert back to the previous release, refer to tag [[https://github.com/dokufreaks/plugin-filelist/releases/tag/2020-09-27|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 [[https://github.com/dokufreaks/plugin-filelist/pull/39|pull request]].
===== Path Configuration =====
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 the ''allowed_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 the ''web_paths'' config option.
All the above things are configured in the ''paths'' configuration (using the [[plugin:config|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.
===== Other Config Options =====
There are a few more options you can set in the [[plugin:config|Configuration Manager]].
* ''allow_in_comments'' Whether to allow the usage of the filelist syntax in comments by the [[discussion|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.
===== Usage =====
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 [[man>fnmatch(5)|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 [[#parameters|below]].
==== Parameters ====
^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 |'', '' |