DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:filelist

filelist Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" yes
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" unknown

plugin Provides a syntax for adding linked and sorted lists of files as selected by wildcard based glob patterns to a wiki page

Last updated on
2024-03-13
Provides
Syntax
Repository
Source

Update to 2024-02-27 breaks backwards compatibility, read docs before upgrading

Similar to directorylist, filelisting, medialist

Tagged with download, file, filter, listing, odt

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.

Installation

Search and install the plugin using the 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
  • 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 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.

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 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.

Other Config Options

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.

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 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.

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 ,
plugin/filelist.txt · Last modified: 2024-03-14 15:38 by annda

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki