Implementation of the Filesys::Virtual::Plain API over a Foswiki store
This module provides two FUSE-like file system implementations that are tailored for use with the WebDAVContrib
) though they are general and flexible enough to serve in other applications. The advantage of such a virtual file system is that it's easier to map other applications that assume a full filesystem to working on data from a Foswiki store.
The file systems are implementations of the virtual base class
- A file system layered over a Foswiki store.
- A pure-perl implementation of the same API for accessing files on disk.
for more information on the basic API
this module implements.
A full filesystem is a lot more generic than a Foswiki store, so
there has to be some mapping between what is in the store and the filesystem,
and some constraints on what can and can't be done with the filesystem.
In the default configuration, the store is mapped as follows:
- Webs are directories
- Topics are seen as plain files that have a
.txt extension, e.g.
MyTopic.txt. Other data views, such as
.html, are also available.
- Attachments are stored in a
Topic_files/ directory, e.g.
Foswiki access controls are respected at all levels in the store.
Note: You cannot
create subdirectories in a
The module currently uses
methods with the absolute minimum
of unavoidable kick-down to the file system when the Foswiki APIs just don't
provide the required information. The unavoidable kick-down means that this
module will only work with filesystem-based stores, such as
The module also supports a simple lock API, which is driven by the requirements
of WebDAV. This lock implementation does not
relate in any way to Foswiki
leases or atomic locks; it is purely for the support of WebDAV clients that
extended attributes and locks. This is primarily used for testing
WebDAVContrib, by providing that module with a full filesystem interface. It
is not directly useful to Foswiki but is provided as a reference implementation
of the file system interface that the WebDAVContrib
requires, and may be useful
as a stand-alone solution to publish files on disk via WebDAV. Note however
that this filesystem does not support user logins.
Foswiki topics are stored internally in TML (Topic Markup Language). TML is
the special wiki markup syntax you see if you "Raw View" a topic. Also mixed
into topics is meta-data, such as form fields.
Neither TML nor meta-data are supported by commonly available editing tools,
such as word processors. So FilesysVirtualPlugin supports different views
of the data
in topics for read and write. Each view you enable adds another file type to
the directory representing a web. For example, if you enable the
views you will see the following files for
Any of these files can be written to change the content of MyTopic.
The following standard views are available:
| Presents just the TML text of the topic in a .txt file.
| Topic text a
.html file (mapping provided by the WysiwygPlugin). This allows you to edit topics using an HTML-capable editor.
| Meta-data in JSON format in a
| Meta-data as a serialised perl data structure in a
| Presents the raw text of the topic in a
.raw.txt file. The raw topic text includes embedded meta-data macros.
You can choose which views you want using the Foswiki
Additional views can easily be added.
method of the
API is implemented
slightly differently to provide better support for Foswiki. Rather than
- style list of files, it returns a full HTML web page.
The web page is built using the
system, using the template file
The FilesysVirtualPlugin does not provide an implementation of this
template. However you can find an implementation in the companion
. Foswiki skin settings are respected, so overriding
this template for customisation is straightforward.
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.
Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button.
Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not
show up in the
You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
perl tools/extension_installer <NameOfExtension> install
If you have any problems, or if the extension isn't available in
, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions
for more help.
Note: This plugin doesn't actually have to be enabled in order to work.
At the moment it uses standard Foswiki access control checking methods,
but the plan is to add a permissions cache. For this reason it has to be
a plugin so it can implement handlers that watch for topic saves.
Note that locks are stored in a database file, held in the working area
for the plugin - usually
. You can
delete this file at any time to automatically release all outstanding locks.
Note that for reasons of efficiency the lock database is leaky (locks on deleted
files may persist). For this reason it is recommended that the lock database
is monitored and deleted during system maintenance if it grows too big.
This software is released under the GNU Public License, version 2. However it
cost a lot in blood, sweat and tears to develop, and if you find it useful
would be grateful for your financial support.
Many thanks to the following sponsors for supporting this work:
|Data::Dumper||>=0||Required perl module|
|Filesys::Virtual||>=0||Required perl module|
|Storable||>=0||Required, used for the locks database|
|POSIX||>=0||Standard perl module|
|File::Path||>=0||Standard perl module|
|IO::File||>=0||Standard perl module|
|IO::String||>=0||Required perl module|
|Foswiki::Plugins::WysiwygPlugin||>=0||Optional, required for .html view|
|JSON||>=0||Optional, required for the .json view|