Attachment List Plugin

Displays a formattable list of topic attachments - from any topic - anywhere in a topic.

View permissions are honored: if the user is not allowed to view the referring topic, the attachments are not displayed.

This plugin uses Foswiki:Extensions/TopicDataHelperPlugin

Syntax Rules

• %ATTACHMENTLIST% - default rendering of the attachment of the current topic
• %ATTACHMENTLIST{parameters}% - see list of parameters below

Topics to search

Parameter	Comment	Default value	Example
topic	Topic name to show attachments of. Possible values: • one topic • a comma-separated list of topic names • a wildcard * to search in all topics in the web; exclude topics using excludetopics	the current topic	topic="AttachmentListPlugin", topic="AttachmentListPlugin, WebHome", topic="*"
excludetopic	Comma-separated list of topic names to not show the attachments of	none	excludetopic="WebPreferences, WebHome"
web	Web name to show attachments of. Possible values: • one web • a comma-separated list of web names • a wildcard * to search in all webs; exclude topics using excludeweb	the current web	web="Extensions", web="Extensions, Main", web="*"
excludeweb	Comma-separated list of web names to not show the attachments of	none	web="*" excludeweb="System"

Attachments to include/exclude

Parameter	Comment	Default value	Example
limit	The maximum number of files to display.	no limit	limit="10"
file	Comma-separated list of attachment file names to explicitly show, possibly generated from a search. The files should be attached to the topics passed in topic. Can be used to show just one or two attachments from a topic.	none	file="ReadMe.txt"
excludefile	Comma-separated list of filenames to not show, possibly generated from a search	none	excludefile="ReadMe.txt"
includefilepattern	Regular expression pattern to match filenames to show. For example: the pattern ^[A-Z] will match files which filenames start with an uppercase letter; pattern [0-9] will find files that have a number in the filename. Use prefix (?i) for case insensitivity.	none	includefilepattern="^(?i)[A]"
excludefilepattern	Regular expression pattern to match filenames to hide.	none	excludefilepattern="^(?i)[B]"
extension	Comma-separated list of file extensions to be listed. To find files that do not have an extension, pass special name NONE.	none	extension="gif, jpg, NONE"
excludeextension	Comma-separated list of file extensions to not show	none	excludeextension="htm"
user	Comma-separated list of user names (that have attached an attachment) to be listed. To find attachments where no user is specified, use UnknownUser.	none	user="ProjectContributor"
excludeuser	Comma-separated list of user names (that have attached an attachment) to not show	none	excludeuser="ProjectContributor, AdminUser, WikiGuest, UnknownUser"
hide	Set to "on" to show only non-hidden attachments	show all attachments	hide="on"
fromdate, todate	Date range filter: show attachments between fromdate and todate; dates are specified in format yyyy/mm/dd • fromdate="" todate="2007/09/01" selects all attachments up to 1 Sep 2007 • fromdate="2007/12/01" todate="" selects all attachments since 1 Dec 2007	no date filter	fromdate="2005/01/01" todate="2007/01/01"
filter (deprecated)	Use extension or includefilepattern

Sort options

Parameter	Comment	Default value	Example
sort	Sorts the retrieved attachments on: name ($fileName) size ($fileSize) user ($fileUser) date ($fileDate) comment ($fileComment) extension ($fileExtension) containing topic ($fileTopic) The sort order can be specified with parameter sortorder.	$fileName	sort="$fileDate"
sortorder	Lists sorted attachments: ascending or descending. The default sort order depends on the sort type: =descending=: default for $fileDate (latest file first) =ascending=: default for $fileName, $fileUser and $fileTopic (alphabetically)	see left	sortorder="ascending"

Formatting parameters

Parameter	Comment	Default value	Example
format	Format string; use the format in the table below. To render images, use format parameter $imgTag (see also plugin setting IMAGE_FORMAT).	Plugin setting FORMAT or IMAGE_FORMAT	format="   * [[$fileUrl][$fileName]]" To create a list of images, use: extension="jpg,jpeg,gif" format="   * <a href='$fileUrl'>$imgTag</a>"
separator	String to separate listed entries	none	separator=","
header	A header text in case of hits	no header	header="All files:"
footer	A footer text in case of hits	no footer	footer="Number of files: $fileCount"
alt	Alternative text if nothing is found	none	alt="No files found"

Formatting variables

These variables can be used in the format tag:

Format variable	Comment
$fileName	Name of the attachment
$fileSize	Attachment size in bytes
$fileExtension	Attachment extension
$fileIcon	Icon image representing this attachment type (see DocumentGraphics) (wraps VarICON around $fileExtension)
$fileComment	Attachment comment
$fileUser	Who has attached
$fileDate	When was attachment attached
$fileUrl	URL of the attachment, assumes ATTACHURL path
$fileTopic	Topic the attachment resides in
$fileWeb	Web the attachment resides in
$viewfileUrl	Full path with viewfile as script name
$fileActionUrl	Full path of management URL for this file (for changing properties etcetera)
$imgTag	Render an image tag using IMAGE_FORMAT; see format parameter above
$imgHeight	Height of image in pixels
$imgWidth	Width of image in pixels
$hidden	'hidden' if the attachment is hidden, nothing otherwise

These substitution variables can be used in the format, header and footer tags:

Format variable	Comment
$n or $n()	New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar
$nop or $nop()	Is a "no operation".
$quot	Double quote (")
$percnt	Percent sign (%)
$dollar	Dollar sign ($)
$br	<br /> tag

These variables can be used in the header and footer tags:

Format variable	Comment
$fileCount	Number of listed files
$fileExtensions	Comma-separated list of extensions of listed files

Test

%ATTACHMENTLIST{
web="%SYSTEMWEB%"
topic="FileAttachment"
format="| $fileIcon | [[$fileUrl][$fileName]] ($fileSize) | Submitted by $fileUser on $fileDate | $fileComment |<span class='foswikiGrayText'>[[$fileActionUrl][manage]]</span> |"
}%

Output (if installed):

%ATTACHMENTLIST{ web="System" topic="FileAttachment" format="| $fileIcon | $fileName ($fileSize) | Submitted by $fileUser on $fileDate | $fileComment |manage |" }%

Image output

%ATTACHMENTLIST{
topic="WabiSabi"
web="%SYSTEMWEB%"
extension="jpg,jpeg,gif,png"
header="Images:"
format="<div class='foswikiImage'><a href='$fileUrl'>$imgTag</a></div>"
separator="<hr />"
footer="Number of images: $fileCount"
}%

Output (if installed):

%ATTACHMENTLIST{ topic="WabiSabi" web="System" extension="jpg,jpeg,gif,png" header="Images:" format="" separator="

---

" footer="Number of images: $fileCount" }%

Regular expression filter

List all files since 01 Jan 2007, starting with a letter 'a' or 'A'. Note the use of the prefix (?i) for case insensitivity.

%ATTACHMENTLIST{
web="%SYSTEMWEB%"
topic="*"
header="Files since 01 Jan 2007, starting with a letter 'a' or 'A':"
footer="Number of files: $fileCount"
format="   * $percntICON{$fileExtension}$percnt [[$fileUrl][$fileName]] $fileComment"
includefilepattern="(?i)^[A]"
fromdate="2007/01/01"
sort="$fileName"
}%

Output (if installed):

%ATTACHMENTLIST{ web="System" topic="*" header="Files since 01 Jan 2007, starting with a letter 'a' or 'A':" footer="Number of files: $fileCount" format=" * $percntICON{$fileExtension}$percnt $fileName $fileComment" includefilepattern="(?i)^[A]" fromdate="2007/01/01" sort="$fileName" }%

Plugin Settings

You can override the default settings for the plugin by defining the following preferences in SitePreferences.
Use the notation NAMEOFPLUGIN_NAMEOFSETTING, for example: ATTACHMENTLISTPLUGIN_DEBUG

Preference	Meaning	Default
FORMAT	Default format of rendering the attachments	\n   * [[$fileUrl][$fileName]] $fileComment
IMAGE_FORMAT	Default format of rendering image attachments. You may specify image height and width parameters - this will read the imaage file and deduct the image size (this will cost performance): <img src='$fileUrl' height='$imgHeight' width='$imgWidth' alt='$fileComment' title='$fileComment' />	<img src='$fileUrl' alt='$fileComment' title='$fileComment' />
DEBUG	If set to 1, writes debugging info to data/debug.txt	0

Installation Instructions

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

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!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Change History:
14 Jul 2017	v1.6 Crawford Currie: unicode fixes
24 Aug 2011	v.1.5.0 Arthur Clemens: sort on attachment comments.
14 Dec 2010	v.1.4.0 Support attachments in subwebs. Foswiki:Main.WillNorris, Support AutoAttachPubFiles -- Foswiki:Main.GeorgeClark
01 Apr 2010	V.1.3.4 Arthur Clemens: Fixed unit tests.
22 Jun 2009	V.1.3.3 Arthur Clemens: Fixed call to unreleased internal function openAttachment.
20 Jun 2009	V.1.3.2 Arthur Clemens: Fixed unit tests; for performance, plugin settings must now be done in SitePreferences.
8 Jun 2009	V.1.3.1 ported to Foswiki -- Foswiki:Main.WillNorris
24 Oct 2008	V.1.3 Arthur Clemens: Added sorting on $fileTopic. For performance, attachments are no longer sorted by default; you must explicitly pass the $sort parameter. Added param file to explicitly list attachments. Added special extension placeholder NONE to find attachments that do not have an extension. Major code refactoring. Created unit tests. Various small bug fixes.
17 Oct 2008	V.1.2.7 Fixed bug with undefined todate.
20 Feb 2008	V.1.2.1 - 1.2.3 Arthur Clemens: Fixed error with format tokens on TWiki older than 4.2; by default sort files by name.
20 Feb 2008	V.1.2 Arthur Clemens: Added parameter includefilepattern and formatting parameter $fileExtension. When using parameter sort the files are now secondary sorted on filename. Added decoding of format tokens.
19 Feb 2008	V.1.1.5 Arthur Clemens: Fix display of header.
25 Jan 2008	V.1.1.4 Arthur Clemens: Removed redundant spacing when no header is defined.
04 Jan 2008	V.1.1 Arthur Clemens: Added filter parameters user and excludeuser; added format parameters $fileTopic and $fileWeb.
06 Dec 2007	V.1.0 Arthur Clemens: integrated sort options by TWiki:Main.RohanMoitra. Renamed FileListPlugin to AttachmentListPlugin; changed FILELIST (now deprecated) to ATTACHMENTLIST.
21 Nov 2007	V.0.9.3 Arthur Clemens: added rendering of images; added $fileExtensions and limit.
20 Nov 2007	V.0.9.2 Arthur Clemens: deprecated filter in favor of extensions; added more options.
18 Jun 2007	V.0.9.1 TWiki:Main/AntonioTerceiro: added support for handling hidden attchments.
08 Apr 2007	V.0.9 TWiki:Main.OliverKrueger: added header, footer and alt params.
17 Dec 2006	V.0.8 Arthur Clemens: reworked for TWiki 4.1 and optimized; activated filter parameter, added topic view permission check.
03 Mar 2006	V.0.7 TWiki:Main.SopanShewale: reworked for TWiki 4
11 Apr 2005	V.0.6 TWiki:Main.VinodKulkarni: Initial version
Dependencies:	Name Version Description Foswiki::Plugins::TopicDataHelperPlugin Required