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.

Syntax Rules

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

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="TWiki/", web="TWiki/, Main", web="*"
excludeweb	Comma-separated list of web names to not show the attachments of	none	web="*" excludeweb="TWiki"
limit	The maximum number of files to display. This setting has no cosequences for rendering time.	no limit	limit="10"
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"
hide	Set to "on" to show only non-hidden attachments	by default the 'hidden' property is ignored	hide="on"
filter (deprecated)	Use extension or includefilepattern
extension	Comma-separated list of file extensions to be listed	none	extension="gif, jpg"
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	none	user="TWikiContributor"
excludeuser	Comma-separated list of user names (that have attached an attachment) to not show	none	excludeuser="TWikiContributor,TWikiAdminUser,TWikiGuest,UnknownUser"
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]"
sort	Sorts the retrieved attachments on either name ($fileName), size ($fileSize), user ($fileUser), date ($fileDate) or extension ($fileExtension). 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: âￜ¢ sort on $fileDate: descending (latest file first) âￜ¢ sort on $fileName or $fileUser: ascending (alphabetically)	sortorder="ascending"
fromdate, todate	Date 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 up from 1 Dec 2007	no date filter	fromdate="2005/01/01" todate="2007/01/01"

Formatting parameters

These parameters can be used in the format tag:

Format parameter	Comment
$fileName	Name of the attachment
$fileSize	Attachment size in bytes
$fileExtension	Attachment extension
$fileIcon	Icon image representing this attachment type (see TWikiDocGraphics) (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 parameters can be used in the format, header and footer tags:

Format parameter	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 parameters can be used in the header and footer tags:

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

Test

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

Output (if installed):

	Sample.txt (30b)	Submitted by TWikiContributor on 22 Jul 2000 - 16:37	Just a sample	manage
	Smile.gif (94b)	Submitted by TWikiContributor on 22 Jul 2000 - 16:38	Smiley face	manage

Image output

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

Output (if installed):

Images:

Number of images: 1

Regular expression filter

List all files starting with an 'a' or 'A'. Note this uses prefix (?i) for case insensitivity.

%ATTACHMENTLIST{
web="%TWIKIWEB%"
topic="*"
header="Files starting with A:"
footer="Number of files: $fileCount"
format="   * $percntICON{$fileExtension}$percnt [[$fileUrl][$fileName]] $fileComment"
includefilepattern="(?i)^[A]"
}%

Output (if installed):

Files starting with A:

• AbandonedFactory.png
• addon.gif
• air.gif
• alltagcloud.gif Screenshot of view all tags tag cloud
• application.gif
• ApprovalFlow.png Saved by install script
• arrowbdown.gif
• arrowbleft.gif
• arrowbright.gif
• arrowbup.gif
• arrowdot.gif
• arrowdown.gif
• arrowleft.gif
• arrowright-small.gif
• arrowright.gif
• arrowup.gif
• as.gif
• attachfile.gif
• AUTHORS

Number of files: 19

Plugin Settings

• Default format of rendering the attachments:

      * Set FORMAT = \n   * [[$fileUrl][$fileName]] $fileComment

• Default format of rendering image attachments:

      * Set IMAGE_FORMAT = <img src='$fileUrl' alt='$fileComment' title='$fileComment' />

• Specify image height and width parameters (switched off for performance; enable by removing the # sign):

      * #Set IMAGE_FORMAT = <img src='$fileUrl' height='$imgHeight' width='$imgWidth' alt='$fileComment' title='$fileComment'  />

• Set SHORTDESCRIPTION = Displays a formattable list of topic attachments, anywhere in a topic.
• Set DEBUG = 0

Plugin Installation Instructions

• Download the ZIP file from the Plugin web (see below)
• Unzip AttachmentListPlugin.zip in your root ($TWIKI_ROOT) directory. Content:

  File:	Description:
  data/TWiki/AttachmentListPlugin.txt
  lib/TWiki/Plugins/AttachmentListPlugin.pm
  lib/TWiki/Plugins/AttachmentListPlugin/FileData.pm

• Optionally, if it exists, run AttachmentListPlugin_installer to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
• Alternatively, manually make sure the dependencies listed in the table below are resolved. None
• Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

Plugin Info

Authors:	TWiki:Main.VinodKulkarni, TWiki:Main.SopanShewale (2006), TWiki:Main.ArthurClemens (2006, 2007, 2008)
Copyright ©:	TWiki:Main.VinodKulkarni, TWiki:Main.SopanShewale (2006), TWiki:Main.ArthurClemens (2006, 2007, 2008)
License:	GPL
Dependencies:	None
Plugin Version:	28 Jul 2008 (V1.2.6)
Change History:
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	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	TWiki:Main.ArthurClemens: 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
Home:	http://TWiki.org/cgi-bin/view/Plugins/AttachmentListPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/AttachmentListPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/AttachmentListPluginAppraisal

. Renamed FileListPlugin to AttachmentListPlugin; changed FILELIST 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	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	TWiki:Main.ArthurClemens: 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
Home:	http://TWiki.org/cgi-bin/view/Plugins/AttachmentListPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/AttachmentListPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/AttachmentListPluginAppraisal