• View
• Edit
• Upload
• History
• Print

Attachlist

<< | Page list | >>

This page describes the extended version of the directive (:attachlist:) that is used to list attachments, i.e. uploaded files and directories.

1.  Introduction to the directive (:attachlist:)

The directive (:attachlist:) allows you to list both uploaded files and directories. Various options can be used to control the behaviour (:attachlist:), making it for instance only list files matching a pattern, or only list directories.

Here's a simple example of using (:attachlist:) to list files in the default root (/) directory.

Files in a subdirectory can also be listed:

We will conclude the introduction with a slightly more complicated example. The example will list sub-directories recursively and only list files containing the text 'image'. For the files that are listed, additional detail will be shown. Here is the markup of the example

and it produces the following result:

(:attachlist /SiteTest recurse=yes fmt=detailed filter=svg :)

The rest of this page will now describe the extended version of (:attachlist:) in more detail.

2.  Description of the directive (:attachlist:)

The directive (:attachlist:) is used to list attachments, i.e. uploaded files and/or directories. These attachments are assumed to be stored in directories on the server where the wiki site is installed.

2.1  Syntax

The syntax of (:attachlist:) is as follows

2.2  Arguments

The directive requires a single arugment, <dir>, which is the name of the directory for which to list attachments. In addition, (attachlist:) accepts a variable number of options that can be placed before or after the directory name.

The directory argument can be preceeded by an optional <prefix> that allows listing attachments in completely unrelated directories on the wiki server. They are intended to correspond to the InterMap prefixes in the following sense: If a prefix uploads: is defined, then (:attachlist uploads:/<path>:) should list attachments in the directory that is linked to by uploads:/<path>.

If a prefix is not used, (:attachlist:) will assume a default prefix, typically corresponding to the directory uploads/ where PmWiki is installed.

2.3  Options

This section describes the options of (:attachlist:). Please note that the name of an option is not case sensitive, and that it is usually enough to only give the first significant letters of each option's argument.

When an option accepts several values, the default value is denoted as strong.

Options:

fmt={simple|detailed} (format)

Selects the format of the listing. Detailed means that file size etc is also shown.

recurse={yes|no} (recursive listings)

When this option is yes, the target directory is listed recursively.

filter={|<string>} (filter filenames)

This option allows the listing to be filtered with a regular expression. Also see the option case.

case={yes|no} (case sensitive)

This option controls if the filter is case sensitive or not. Setting case=yes means that the filter will be case sensitive.

listdirs={yes|no} (list directories even when not recursing)

When this option is yes, directories are listed even if their contents aren't shown.

listfiles={yes|no} (list files)

When this option is no, files aren't listed.

itemprefix=<string> (prefix string of each item)

This string is by default '*', which results in an itemized list starting at level one. Setting itemprefix=** results in a list starting at level two instead.

verbose={yes|no} (be extra verbose - for debugging)

When this option is yes, (:attachlist:) produces more verbose output. In practice this is only used for debugging.

noaction={yes|no} (don't produce normal output - for debugging)

When this option is yes, (:attachlst:) is not actually executed but only produces diagnostic output. In practice this is only used for debugging.

3.  Examples

This section gives some examples of how to use directive.

4.  Installation and configuration

In order to install this recipe, download the file http://wiki.lyx.org/local/attachlist.php and place it for instance in your cookbook directory. Then add something like the following to your configuration file, e.g. local/config.php.

include_once("$FarmD/cookbook/attachlist.php");

Next you need to configure the downloaded file appropriately to match your installation of PmWiki.

In order to set define the location of a directory that corresponds to a prefix, add something like this to your configuration file:

$IMapLocalPath['uploads:'] = '/home/lyx/www/pmwiki/uploads';

where in this example 'uploads:' is the name of the prefix and '/home/lyx/www/pmwiki/uploads' is the absolute path to the corresponding directory.

Lots of information that needs to be added...

4.1  Configuration variables

$IMapLocalPath[]

Array that specifies the local path corresponding to intermap prefixes.

Possible configuration choices (to be done...):

• choice of default directory when no prefix is specified
• if a file manager should be used or not
• which file manager to use

Description of option structure used within the implementation

The implementation of (:attachlist:) accepts several internal options which are listed here:

$opts.fmt

String, see the corresponding option above.

$opts.recurse

Boolean, true when directories should be recursed. Also see the corresponding option above.

$opts.filter

String, also see the corresponding option above.

$opts.case

Boolean, true when the filter is to be case sensitive. Also see the corresponding option above.

$opts.listFiles

Boolean, true when to show files.

 Also see the corresponding option above.

$opts.listDirs

Boolean, true when to show directories even when not recursing into subdirectories. Also see the corresponding option above.

$opts.baseDir

Defines the base directory of the directory to be listed.

$opts.baseURI

Defines the base URI for target links in the output.

$opts.verbose

Boolean, true when to show verbose information during execution. For debugging.

$opts.noaction

Boolean, true when to only fake doing things. For debugging.

$opts.matchFcn

String, name of function to call in order to check if a file should be include in the output listing. Also see the options filter and case above.
This function is to be called with $opts and $name as arguments.

$opts.fmtItemFcn

String, name of function to call in order to produce the output of an item (file or directory).
This function will be called with the following arguments:

• $opts - Options structure
• $name - Name of file or directory
• $path - Absolute path to file or directory
• $dir - Relative path to file or directory.

5.  Notes

• Maybe (:attachlist /dir/file:) should work?
• Maybe (:attachlist /dir/glob:) should work?
• Possibly make (:attachlist:) behave more like the original?

Tools