LyX wiki | Playground / UploadListFcn

<< | Page list | >>

Specification of a function for listing uploaded files.

A wiki author would use a special markup to invoke the function. I'll create the markup bit and how it parses its arguments etc. What I'd like from you is a "backend" function that I can invoke to produce the listing. The markup I'm suggesting below will have a few options/parameters, which results in a set of requirements on the function.

Please don't feel you have to implement all of those requirements, I'll be happy with the basics - additional requirements can be added as they are needed. The reason I list a relatively complete specification is primarily to get a good syntax for the markup - otherwise it's quite easy to design a markup which can't be expanded later on.

Also note that the markup I'm suggesting below is just that, a suggestion. If you have comments or would like it differently, let me know!

Anyway, here's a possible syntax of the markup:

(:uploadslist <dir> fmt=<fmt> recurse=<yes|no> filter=<regexp>:)

where

<dir>: Optionally specifies what directory to list, relative to the uploads directory. Eg. 'Windows/LyX14x' would result in a listing of http://wiki.lyx.org/uploads/Windows/LyX14x
<fmt>: Optionally specifies a simple listing or a detailed listing, e.g.
fmt=simple — default, just the file name
fmt=detailed — file name, size, date etc

what we'd like from detailed list is unclear, I'm just guessing that size and modification is enough.

<recurse>: Optionally specifies if the listing should be recursive, e.g
recurse=no — default, just one directory
recurse=yes — descend into subdirectories
<filter>: Optionally allows a filter which only lists matching files, e.g
filter='mpg$' — only files ending with 'mpg'

This then leads to the requirements of the function... Here's how I imagine it:

       $str = UploadListFcn($baseDir, $baseURI, $opts);

where the function should return a file listing either as a snippet of HTML which I'll just insert into the output, or as wiki markup. You choose which you feel is easiest for you. I suspect it's actually easier to do it by returning wiki markup, see further down for a suggestion. As for the arguments, here's how I imagine them:

$baseDir is a string containing the *absolut* path to the "top" directory that should be listed. If there's no recursion, this will be the only directory that is listed of course. For example:
$baseDir = '/home/lyx/pmwiki/uploads/Windows'

Let me know if you'd prefer this string to always end in a '/' or not, or if you make the function so that it doesn't matter.

$baseURI is a string containing a part of a URI, which should be prepended to a file link. This matches '$baseURI', e.g.
$baseURI = 'http://wiki.lyx.org/pmwiki/uploads/Windows'

Same thing goes here if you'd like a '/' at the end or not.

$opts is an array with the remaining options. The array will always have all the elements that are specified, i.e. the following:

       $opts  = array( 'fmt' => $fmt,
                       'recurse' => $recurse,
                       'filter' => $filter);

where

$fmt is one of the strings 'simple' or 'detailed'
$recurse is one of the strings 'yes' or 'no',
$filter is a string with a regular expression (or empty)

As for the output, I don't really have much of an opinion about what it should look like. To me it doesn't make sense to make it too complicated. Here is one suggestion as to what the output could be when returned as wiki markup when invoked from different markups:

The markup (:uploadslist Windows:) results in this invocation:

UploadsListFcn('/home/lyx/pmwiki/uploads/Windows',   
               'uploads:/Windows',
               array('fmt'=>'simple', 'recurse'='no','filter'=>''));

which then returns the following:

* [[file0.txt -> uploads:/Windows/file0.txt]]
* [[file1.txt -> uploads:/Windows/file1.txt]]
...

Here's another example when the function should recurse, based on the markup (:uploadslist Windows recurse=yes:) which would result in this invocation:

     
UploadsListFcn('/home/lyx/pmwiki/uploads/Windows',
               'uploads:/Windows',
               array('fmt'=>'simple','recurse'='yes','filter'=>''));

which then returns the following:

* [[file0.txt -> uploads:/Windows/file0.txt]]
* [[file1.txt -> uploads:/Windows/file1.txt]]
* LyX14x/
** [[file2.txt -> uploads:/Windows/LyX14x/file2.txt]]
...

Finally here's an example of a detailed list, from the markup: (:uploadslist Windows fmt=detailed:):

UploadsListFcn('/home/lyx/pmwiki/uploads/Windows',
               'uploads:/Windows',
               array('fmt'=>'detailed','recurse'='no','filter'=>''));

which then returns the following:

* [[file0.txt -> uploads:/Windows/file.txt]] (105 bytes, 2006-03-21 15:03)
...