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

txt Sample.txt (30b) Submitted by TWikiContributor on 22 Jul 2000 - 16:37 Just a sample manage
gif 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:

Wabi Sabi
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:

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
Topic revision: r1 - 12 Apr 2005 - 09:03:54 - TWikiContributor

 
This site is powered by the TWiki collaboration platformCopyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.AttachmentListPlugin