Differences

This shows you the differences between two versions of the page.

--- plugin:filelist [2016-05-14 15:28] – [Parameters]: added 'preview' LarsDW223
+++ plugin:filelist [2024-04-03 23:50] (current) – version upped andi
@@ Line 6: / Line 6: @@
 email      : freaks@dokuwiki.org
 type       : syntax
-lastupdate : 2016-05-14
+lastupdate : 2024-04-03
-compatible : Binky, Ponder Stibbons, 2014-09-29 "Hrun"
+compatible : Jack Jackrum, Kaos
 depends    :
 conflicts  :
 similar    : medialist
-tags       : file, listing, download, media, filter
+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
@@ Line 17: / Line 19: @@
 sourcerepo : https://github.com/dokufreaks/plugin-filelist/
 donationurl:
+screenshot_img : https://github.com/dokufreaks/plugin-filelist/raw/master/FilelistScreenshot.png
 ----
-====== Detailed Information ======
-See the developer's webpage:
+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.
-  * [[http://foosel.org/snippets/dokuwiki/filelist|Details and Download]]
-  * [[http://foosel.org/snippets/dokuwiki/filelist#usage | Syntax & Usage]]
-:!: This plugin has currently got an open issue since DokuWiki release "hrun" (so also with "detritus"). If you use the option ''style=page'' then you will get a blank page which is not editable any more unless you disable the filelist plugin. Also see issue [[https://github.com/dokufreaks/plugin-filelist/issues/11|issue #11]] in the github issue tracker. :!:
+===== Installation =====
-====== Description ======
+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
-I have copied the essentials from the developer's web site, since the links are broken. \\
---- [[user>turnermm|Myron Turner]] //2015-06-09 03:39//
-The original page with illustrated examples are here: http://web.archive.org/web/20150411215519/http://www.foosel.org/snippets/dokuwiki/filelist.  This link was provided in a post on the forum (https://forum.dokuwiki.org/thread/12665).  Please make any necessary changes.
+==== Upgrade from older Versions ====
-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.
+Release 2024-02-27 is a complete refactoring of the old plugin. The following features have been removed:
-The Git repository of the plugin can be found [[http://web.archive.org/web/20150411215519/https://github.com/dokufreaks/plugin-filelist|at Github]].
+  * 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)
-====== Configuration ======
+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]].
-The filelist plugin has three configurable options:
+Path configuration differs from previous releases. Please see below to set up your paths again.
-^Option ^Description |
+Some more info is available in the [[https://github.com/dokufreaks/plugin-filelist/pull/39|pull request]].
-|''allow_in_comments''   |Whether to allow the usage of the filelist/filename syntax in comments by the [[http://web.archive.org/web/20150411215519/http://wiki.splitbrain.org/plugin:discussion|discussion plugin]]. Defaults to ''0'' and thus prohibition of the plugin usage in this scenario.  |
-|''allowed_absolute_paths''   |A comma-separated whitelist of all paths beneath which to allow the scanning using the filelist/filename syntax. Defaults to the Dokuwiki basedir ''DOKU_INC''.  |
-|''web_paths''   |A comma-separated list of URLs via which the previously defined absolut paths are reachable to wiki users. This list **MUST** contain exactly the same amount of entries as ''allowed_absolute_paths''. Defaults to the Dokuwiki base-URL ''DOKU_URL'' as a mapping for ''DOKU_INC''.  |
-===== Usage =====
+===== Path Configuration =====
-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:
+To use this plugin, you need to configure one or more **paths** that should be allowed for listings.
-<code>
-{{[ command ]>[ pattern ][ parameterlist ]}}
-</code>
-  * **command**  must be either ''filelist''  or ''filename''.
+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).
-  * **pattern**  is a searching pattern for files to include in the generated list, defined using the [[http://web.archive.org/web/20150411215519/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/''  ((2)) ) , you would use''some''''/path/*.txt''  as the pattern (and the parameter ''direct=1'', see [[#parameters|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 ====
+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!
-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 [[http://web.archive.org/web/20150411215519/http://www.foosel.org/snippets/dokuwiki/filelist#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.
+> Note: in older plugin versions the paths were configured in the ''allowed_absolute_paths'' config option.
-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''.
+For each configured path an optional **alias** may be configured. This alias will simplify the syntax when using the plugin (see examples below).
-==== Parameters ====
+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.
-^Name ^Description ^Possible values ^Default |
+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.
-|''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''   |
-|''cache''   |Whether to disable or enable caching for the page. Default is no caching. |''0'' or ''1''   |''0''   |
-^  ^''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''   |Deprecated, see ''showdate''. Off by default. |''0'' or ''1''   |''0''   |
-|''tableshowsize''   |Deprecated, see ''showsize''. 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 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''   |
-|''preview''        |Whether to show a preview image for image files. Off by default. |''0'' = off,\\ ''1'' = image and file icons,\\ ''2'' = image only,\\ ''3'' = file icon only   |''0''   |
-^  ^''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 =====
+> Note: in older plugin versions the web prefixes were configured in the ''web_paths'' config option.
-=== filelist ===
+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 1 ==
+**Example**
 <code>
-{{filelist>:snippets:dokuwiki:plugin-*.tar.gz&style=table&tableheader=1&tableshowdate=1&tableshowsize=1}}
+\\somewindows.server\with\a\share
+  W> https://somewindows.server/has/itsowndocroot/
+  A> fileserver
+/this/is/a/local/path/outside/thewebroot/
+  A> local
 </code>
+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 =====
-== Example 2 ==
+There are a few more options you can set in the [[plugin:config|Configuration Manager]].
-<code>
+  * ''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.
-{{filelist>lib/images/*&style=list&direct=1}}
+  * ''defaults'' Syntax defaults that should always apply to all syntax invokes. See usage section for details.
-</code>
+  * ''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.
-== Example 3 ==
-<code>
+===== Usage =====
-{{filelist>lib/images/*&style=olist&direct=1&recursive=1&sort=iname}}
-</code>
-====== Discussion ======
-links are there now i think :
-https://github.com/dokufreaks/plugin-filelist/archive/master.zip
-https://github.com/dokufreaks/plugin-filelist
-----
-The links to the details description and syntax seem to be not working, so we're not able to work out how this plugin works --- //Simon, 29 May 2015//
-----
-Works with my DokuWiki version //2010-11-07//. A problem was discovered, which is the filelist does not display the files for unregistered user. The ACL is correctly set for ALL and using normal syntax the file is displayed and accessible. --- // Münchener, 14 Feb 2011//
-----
-I played around with getting this to work for a while, before realising that, under Windows, the case of the drive letter does actually matter!  So, both [[config:savedir]] and this plugin's ''allowed_absolute_paths'' I had to change from ''d:/www-data/wiki/'' to ''D:/www-data/wiki/'' --- [[user>samwilson|samwilson]] //2011-10-05 05:46//
-----
-I had no end of trouble getting this to work on Bitnami WAMPStack Server (Windows, Apache, MySQL, PHP). I finally discovered that not only is the case of the path important, the mix of \ and / path separators used in the dokuwiki config path is important. It works now that I used the exact path specified in the dokuwiki "savedir" config, eg ''C:\Program Files\Bitnami WAMPStack\apps/dokuwiki/data/'' (and no quotes). Obvious once stated. --- **alan** //2012-12-04 11:58//
-----
-In my judgement this plugin does not work with Rincewind. At least not in my configuration. In Rincewind I could this only get working with the direct-option and absolute paths, not the namespace notation. The namespace-notation resulted in Access-denied.
-And 'working' means only display, clicking on a file-link in the list resulted in a server-error :-(
-The medialist-plugin is a working alternative (if using a patch somebody provided in the dokuwiki-documentation).
-Examples:
+The filelist plugin provides a new syntax to list files. The general command syntax is the following:
-So this displayed a list
 <code>
-{{filelist>data/media/natuurlijk/documents/*.*&style=table&direct=1&tableheader=1&tableshowdate=1&tableshowsize=1&sort=iname}}
+{{filelist>[ pattern ][ parameterlist ]}}
 </code>
-This did NOT:
+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.
-<code>
+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>:natuurlijk:documents:*.*&style=table&direct=1&tableheader=1&tableshowdate=1&tableshowsize=1&sort=iname}}
-</code>
-Omission of //&direct// won't work either.
+  {{filelist>fileserver/foo/*.txt}}
-There seems to be no real alternative to this plugin, it would be nice if this could be repaired (or my mistake in the usage of it be clarified)
-The bug-report link on the owner's list points to nirvana :-(
-----
+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]].
-**It works with Rincewind and Angua.**
+==== Parameters ====
-I had to go to //Admin > Configuration Settings > Filelist Plugin Settings// and give values like the following:
+^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''   |
-|plugin»filelist»web_paths              |<code>/home/myuser/        </code>|
+|''order''   |Whether to sort the internal file list ascending or descending. Sorting in ascending order is the default. |''asc'',''desc''   |''asc''   |
-|plugin»filelist»allowed_absolute_paths |<code>file:///home/myuser/ </code>|
+|''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''   |
-[[http://en.wikipedia.org/wiki/File_URI_scheme|More information from Wikipedia.]]
+|''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''   |
-I also had to consider [[http://kb.mozillazine.org/Firefox_:_Issues_:_Links_to_Local_Pages_Don%27t_Work|this]]. Firefox blocks links to local files for security purposes. So I added the LocalLink extension to Firefox, as described in that page.
+|''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''   |
-With this modifications, I can use something like this:
+|''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''   |
-  {{filelist>/home/myuser/Desktop/*&direct=1}}
+|''listsep''     |List separator to use between the fields (e.g. //"linktext, showsize"//). Default is '', ''. |Any character sequence   |'', ''   |
-or like this:
-  {{filelist>/home/myuser/Desktop/*&direct=1&style=olist&recursive=1&sort=iname}}
-to list the contents of my file system.
-In Firefox with the LocalLink extension, one may right-click on a link/element from that list and select //Open Link In Local Context//.
-I have tested this in Mac OS X and Ubuntu. I have made a trial in Windows 7 with the following values (also trying lower case ''c:'') but I could not make it work and I got ''[n/a: Access denied]''.
-|plugin»filelist»web_paths              |<code>C:/Users/Myuser/ </code>|
-|plugin»filelist»allowed_absolute_paths |<code>file:///C:/Users/Myuser/ </code>|
-  {{filelist>C:/Users/Myuser/Desktop/*&direct=1}}
------
-This
-  {{filelist>:wiki:asorted:pcard:201203:*.*&style=list&direct=0}}
-works without any modification as expected in Rincewind
-===== Binky =====
-After upgrading to Binky, previously working code now displays:
-<code>[n/a: Access denied]</code>
-I am logged in as admin and have made no changes to ACL rules.
-The configuration settings have not changed, path on server & url are correct:
-My previously working entries were of different format to discussion above (as follows):
-|plugin>>filelist>>allowed_absolute_paths| <code>/home/users/web/ourmockseverpath/htdocs/</code>|
-|plugin>>filelist>>webpaths| <code>http://www.ourmockseverurl.org.au/</code>|
-Has anyone got this very useful plugin working on Binky?
- --- [[user>charles.minto|charles.minto]] //2014/01/24 00:44//
-All these:
-<code>
-{{filelist>:playground:test:*.*&style=table&tableheader=1
-  &tableshowdate=1&tableshowsize=1&sort=iname}}
-{{filelist>:playground:test:*.doc*&style=table&tableheader=1
-  &tableshowdate=1&tableshowsize=1&sort=iname}}
-{{filelist>:playground:test:*.pdf&style=table&tableheader=1
-  &tableshowdate=1&tableshowsize=1&sort=iname}}
-</code>
-work as expected on Binky.
-JohnG //2014-02-12//
-Thanks. I finally figured out the problem, my mistake. I had to change my entry in the configuration settings from ''DOKU_INC'' to:
-|plugin>>filelist>>allowed_absolute_paths| <code>/home/users/web/ourmockseverpath/htdocs/subfolder/</code>|
-as the weburl.com.au points to the subfolder.
- --- [[user>charles.minto|charles.minto]] //2014/03/19 11:55//
-Actually after tracing through the file list code using basically print statements, I found out what wasn't working for me. I thought I should post that by default out of the box if you haven't changed paths much, then you want the allowed_absolute_paths to point to your sites dokuwiki/data/media directory and you want your URL to be to your site. So for us we have something like
-|plugin>>filelist>>allowed_absolute_paths| <code>/home/deploy/rubystack-bitnami/apps/dokuwiki/data/media</code>|
-|plugin>>filelist>>webpaths| <code>http://www.yourserver.com/</code>|
-Then in the actual code, to for example list all files in the media director of the form Notes*.pdf for the name space project,  we use something like:
-<code>{{filelist>:project:Notes*.pdf&style=list&sort=iname}}</code>
- --- [[user>jasonharris|jasonharris]] //2014/04/27//
-It still doesn't work for me in Hrun. I set
-|plugin»filelist»allowed_absolute_paths| <code>/usr/local/dokuwiki/data/media/</code>|
-|plugin»filelist»web_paths| <code>http://our.server.tld/</code>|
-but I get ''Access denied'' when I use the ''filelist'' plugin on my pages
- --- Hana Skoumalová //2014/12/18//
-===== Hrun =====
-The default setting ''DOKU_INC'' for the absolute path did not seem to work. It just got me the dreaded //access denied// message. However, I was able to get the plugin working by:
-  * set the absolute path to ''/usr/local/doku/data'' on a server administrated by me.
-  * set the absolute path to ''/'' on a shared space hosted by an ISP. In this case I also set the DOKU_URL to the URL this wiki can be reached.
- --- [[user>KaiMartin|KaiMartin]] //2015-02-09 03:16//
-on my dokuwiki hrun on a synology NAS and using multiple [[doku>farms|animals]], i only got it working with:
-  * plugin»filelist»allowed_absolute_paths = ''/var/services/web/wiki/dokumente/data/media/''
-  * plugin»filelist»defaults = ''/wiki/dokumente/_media/''
-where
-  * ''/var/services/web'' is the path given by _SERVER["HOME"] using [[phpfn>phpinfo]]
-  * ''/wiki/dokumente'' is the path for the animal. in generell i think it will be just ''/dokuwiki''
-by using the ''direct'' parameter and absolute path like this: ''%%{{filelist>/var/services/web/wiki/dokumente/data/media/*&direct=1&recursive=1}}%%''
-===== Detritus =====
-The setting ''DOKU_INC'' works as expected in Detritus. If you still get access denied messages, the cause may be an inappropriate setting of the ''direct='' parameter. --- [[user>KaiMartin|KaiMartin]] //2015-10-12 23:24//
-==== Filelist Future proof? ====
-Great plug-in but seems old and a bit unstable now and then? Our intranet depends on it because of the great real-time connection between file actions in 'windows explorer' and the file lists in the wiki (indirect via mounting of certain directories on a Windows server). Is there anything a non-coding user like me could do to keep an essential plugin like this one future-proof?
-\\ ----2016.03.31 17:05 - MartinNL
-> You can always pay someone to maintain this plugin. See [[faq:support#bounties]] and [[faq:support#professional support and services]] (although you might be more successful finding someone elsewhere). --- [[user>ach|Anika Henke]] //2016-04-03 19:23//
->> Thank you, I am going to discuss this here.
- ----2016.04.04 08:15 - MartinNL