Attachment List Plugin

Displays a formattable list of topic attachments, 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    
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"
excludefile Comma-separated list of filenames to not show, possibly generated from a search none excludefile="ReadMe.txt"
sort Sorts the retrieved attachments on either name, date or user. The sort order can be specified with parameter sortorder. no sort sort="$fileName"
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 file
$fileIcon Icon image representing this file type (see TWikiDocGraphics)
$fileSize File size
$fileComment Attachment comment
$fileUser Who submitted
$fileDate When submitted
$fileUrl URL of the file, assumes ATTACHURL path
$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 parameterup Comment
$br <br /> tag
$n newline character

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 - 19:37 Just a sample manage
gif Smile.gif (94b) Submitted by TWikiContributor on 22 Jul 2000 - 19: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

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)
Copyright ©: TWiki:Main.VinodKulkarni, TWiki:Main.SopanShewale (2006), TWiki:Main.ArthurClemens (2006, 2007)
License: GPL
Dependencies: None
Plugin Version: 06 Dec 2007 (V1.0.1)
Change History:  
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