TopicInteractionPlugin

Improved interaction with attachments and DataForms

Description

This plugin redesigns the way how users interact with topics and attachments in various ways:

• improved attachment handling
• improved visuals displaying DataForms
• improved integration of Foswiki:Extensions/MetaCommentPlugin and Foswiki:Extensions/FlexPaperPlugin

Other features are:

• cross-browser compatible bulk upload of multiple files
• bulk actions on attachments: delete, move, hide, download as zip archive, create image gallery, insert links
• thumbnail and lightbox preview of image attachments
• easy renaming of attachments using modal dialogs
• easy access to previous revisions of attachments
• loading the list of attachments via ajax not to slow down display of topics with lots of attachments
• filtering and pagination for topics with a lot of attachments
• drag & drop upload for browsers supporting it (currently firefox and chrome only)

Screenshots

Settings

To activate you'll need to add topicinteraction to your SKIN path setting in your SitePreferences, like

    * Set SKIN = topicinteraction, pattern

Use the insidetab setting of MetaCommentPlugin to render comments inside a tab at the bottom of the page:

    * Set SKIN = topicinteraction, metacomment, pattern
    * Set DISPLAYCOMMENTS = on
    * Set COMMENTFORMAT = insidetab

Note you won't need using Foswiki:Extensions/NatSkin as that's integrated automatically.

Creating a link to an attachment

TopicInteractionPlugin extens the standard way of inserting links to an attachment. Instead of only distinguishing between images and other kinds of attachments you may now specify different code to be inserted into the topic based on the mime type of an attachment. You may specify a set of various preference settings. The actual setting being used is chosen in the given precedence:

1. ATTACHED_<file-extension>_FORMAT
2. ATTACHED_<mime-type>_FORMAT
3. ATTACHEDIMAGEFORMAT (provided for compatibility, left out in below examples)
4. ATTACHED_FILE_FORMAT
5. ATTACHEDFILELINKFORMAT (provided for compatibility, left out in below examples)

(<file-extension> and <mime-type> are uppercase). For example, when inserting a link to an attachment named screenshot.png the following settings are looked up:

1. ATTACHED_PNG_FORMAT
2. ATTACHED_IMAGE_FORMAT
3. ATTACHED_FILE_FORMAT

The one first found is used. When looking up the link format based on the mime type, the actual mime type group is used, such as IMAGE, VIDEO, TEXT, AUDIO etc just to name the most interesting ones. There are a couple of more mime types that are grouped together in a meaningful way to form the group DOCUMENT which are application/.*(document|msword|msexcel|rtf).*, as well as PDF which are application/pdf and application/postscript.

For example the following settings might be quite useful:

Using DocumentViewerPlugin:

   * Set ATTACHED_ODT_FORMAT = $percntDOCUMENTVIEWER{"$filename"}$percnt
   * Set ATTACHED_PDF_FORMAT = $percntDOCUMENTVIEWER{"$filename"}$percnt

Using ImagePlugin:

   * Set ATTACHED_IMAGE_FORMAT = $percntIMAGE{"$filename" size="200" caption="$comment"}$percnt 

Using MediaElementPlugin:

   * Set ATTACHED_VIDEO_FORMAT = $percntVIDEO{"$filename"}$percnt
   * Set ATTACHED_AUDIO_FORMAT = $percntAUDIO{"$filename"}$percnt

Using WebDAVContrib (please adjust the webdav://wiki/dav prefix to your needs):

   * Set OFFICELINK = <a href='webdav://wiki/dav/%WEB%/%TOPIC%/%DEFAULT{default=""}%' class='jqWebDAVLink' title='Edit Office Attachment' rel='nofollow'>%DEFAULT{default=""}%</a>
   * Set ATTACHED_DOCUMENT_FORMAT = $percntOFFICELINK{"$filename"}$percnt
   * Set WEBDAV_OFFICE_SUITE = msoffice, libreoffice or openoffice (defaults to settings in =configure=)

The ..._FORMAT strings support the following variables:

• $filename: the name of the file
• $fileext: the filename extension (string following the last period, if present) or an empty string.
• $fileurl: URL of the filename
• $comment: the file comment from the upload dialog
• $size: the filesize (%ATTACHEDIMAGEFORMAT% only)
• $width: image width
• $height: image width
• $date: modification date of attachment
• Any standard formatting tokens: $percnt, $dollar, etc.

Incompatibilities

There is a significant difference how Foswiki's natively processes ATTACHEDFILEFORMAT settings and the way TopicInteractionPlugin does.

• Any macro expression must always be escaped using standard format tokens $percnt and $dollar. As such previous settings might be incompatible with TopicInteractionPlugin settings of the same kind.
• The time format specifiers are not supported. Use $date instead.

Syntax

TopicInteractionPlugin implements some macros to actually implement the user interface. These macros can be used for other purposes too of course.

ATTACHMENTS

List all attachments of a given topic. Without any parameters it displays a table of attachments similar to the one generated by the templates at the bottom of a topic. There are a couple of parameters that take regular expressions to limit the number of attachments to be listed.

Syntax:

%ATTACHMENTS%, %ATTACHMENTS{"<topic>" ...}%
"<topic>"	topic with attachments to be included
attr="..."	match the attachments' attribute
autoattached="yes,no,undef"	limit attachments to those that are (not) autoattached
casesensitive="on/off"	specify string comparison mode when filtering attachments, defaults to on
comment="..."	match the attachments' comment
maxdate="..."	specify latest attachment
maxsize="..."	specify biggest attachment
mindate="..."	specify earliest attachment
minsize="..."	specify smallest attachment
names="..."	regular expression matching the name of attachments to be include in the list
user="..."	regular expression matching the attachments' user who uploaded it
include="..."	general regular expression that the name, user, comment and attributes must match
exclude="..."	general regular expression that the name, user, comment and attributes must not match
footer="..."	format string appended to the result
format="..."	how to format each attachment
header="..."	format string prefixing the resulting output
separator="..."	format string put between each formatted attachment
hidenull="on,off"	hide/display the empty result; only the header and the footer are included if set to "off" and there's no attachment at the given topic
nullformat="..."	format string to be used when no attachments have been found and hidenull is switched off
nullheader="..."	header string to be used when no attachments have been found and hidenull is switched off
nullfooter="..."	footer string to be used when no attachments have been found and hidenull is switched off
sort="name,date,size,user,comment,comment:name,random,type"	sort results by specified property
reverse="on/off"	enable reverse sorting
limit="..."	limit the number of attachments to the given number; by default show all
dateformat="..."	custom date format string, defaults to the system's default date format

The following variables can be used in the format parameter:

• $attr: the attributes
• $autoattached: the autoattach flag
• $comment: the comment field
• $date(<format>): the attachment date using <format> to format the date
• $date: the attachment date
• $delete: the action to delete the current attachment
• $deleteUrl: the url used in the delete action
• $extension: file extension of this attachment
• $hidden: 0 or 1 depending on the file being hidden or not
• $icon: img tag representing the filetype, this is either a matching document graphics or using MimeIconPlugin if installed
• $iconUrl: the url pointing to the icon used in the img tag
• $index: the position index of the attachment in the result
• $move: the action to move the current attachment
• $moveUrl: the url used in the move action
• $name: the name of the attachment
• $path: the path property of the attachment
• $props: the action to change the properties of the current attachment
• $propsUrl: the url used in the props action
• $size: the size in bytes
• $sizeH: file size in a humanized display (using KB, MB, GB, etc) as needed
• $sizeK: the size in kilo bytes
• $sizeM: the size in mega bytes
• $sizeG: the size in giga bytes
• $topic: the name of the topic of whose attachments are listed
• $url: the attachments url
• $urlpath: the attachments urlpath
• $user: the user that uploaded the attachment
• $web: the web name of the current topic
• $webdav: the action to edit the current attachment using the Foswiki:Extensions/WebDavPlugin
• $webdavUrl: the url used in the webdav action
• $wikiuser: the user's home topic that recently changed the current attachment
• $movedfrom: location from where an attachment was moved from to the current location
• $movedfromweb: web part
• $movedfromtopic: topic part
• $movedfromname: name of the original attachment
• $movedto: location where an attachment was moved to
• $movedtoweb: web part
• $movedtotopic: topic part
• $movedtoname: name part
• $movedby: name of the user that moved the attachment
• $movedwhen: date when the attachment was moved
• $movedwhen(<format>): date when the attachment was moved with a custom date format string
• $version: version of the attachment
• $oldversions: list of old version information in the format $date;$user;$rev;$comment
• $encode(...): helper to url encode the enclosed string
• $exists: boolean to indicate whether the attachment really exists

The header and footer format strings may only contain

• $count: the number of attachments found
• $extensions: comma separated list of all file extensions

The format, header and footer may contain the standard escape sequences:

• $dollar: $ sign
• $n: newline
• $percnt: % sign
• $quot: " sign

Example:

%ATTACHMENTS{
  header="| * * | *Name* | *Url* | *Size* | *Author* | $n"
  format="| $idnex | $name: | $url | $sizeK |"
}%

generates:

%ATTACHMENTS{ header="| # | Icon | Name | Size | Author | Date |$n" format="| $index | $icon | $name | $sizeK | $user | $date |" }%

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.

Dependencies

Name	Version	Description
Foswiki::Contrib::JQPhotoSwipeContrib	>=1.00	Optional
Foswiki::Plugins::FilterPlugin	>=2.07	Required
Foswiki::Plugins::FlexFormPlugin	>=2.40	Required
Foswiki::Plugins::DocumentViewerPlugin	>=1.0	Optional
Foswiki::Plugins::ImageGalleryPlugin	>=6.00	Optional
Foswiki::Plugins::ImagePlugin	>=2.41	Required
Foswiki::Plugins::JQueryPlugin	>=7.20	Required
Foswiki::Plugins::MediaElementPlugin	>=1.00	Optional
Foswiki::Plugins::MetaCommentPlugin	>=1.11	Optional
Foswiki::Plugins::LikePlugin	>=2.00	Optional
Foswiki::Plugins::MimeIconPlugin	>=1.1	Required
Foswiki::Plugins::RenderPlugin	>=3.01	Required
Foswiki::Plugins::TopicTitlePlugin	>1.00	Required
Archive::Zip	>=0	Required
Digest::MD5	>=2.36	Required
JSON	>=2.17	Required
Foswiki::Plugins::ZonePlugin	>=3.1	Required for Foswiki < 1.1

Change History

30 Apr 2024:	refactored javascript implementation
12 Jul 2022:	remove DRY flag from move-attachment action
01 Jul 2022:	fixed detection of multi-file upload capabilities of foswiki core
29 Jun 2022:	validate web, topic and filename parameters properly; fixed some Perl::Critic violations; support multi-file upload capabilities of newer Foswiki cores
09 Jun 2022:	zip archives need to flag filenames as unicode explicitly; fixed encoding of attachment comments
05 Mar 2022:	added support for a custom TRASHWEB; improved %ATTACHMENTS macro in various ways; allow uploader to be disabled using the %TOPICINTERACTION_UPLOADERENABLED preference setting; sanitizing attachment names using the {UploadFilter}; improved ChangeProperties to be more robust against storage errros; improved "insert link" feature
26 Nov 2018:	added compatibility with AttachmentListPlugin; added support for Foswiki:Extensions/MimeIconPlugin to render attachment icons; added sort by type option to %ATTACHMENTS makro
06 Nov 2018:	removed excess div in templates; moved progress bar into js land
24 Oct 2018:	improved "insert link" action; added "create link & hide file" action; performance improvements to other actions
05 Mar 2018:	fixed selecting attachments with brackets in its filename
16 Feb 2018:	added a legacy uploader to be somewhat backwards compatible to the old plupload just enough to please natedit
16 Jan 2018:	check access permissions in %ATTACHMENTS makro; fixed url encoding of unicode files
13 Sep 2017:	replace outdated plupload uploader with jquery-file-upload
18 Nov 2016:	oo-ified core; added humanized file size display, removed flash backend from default; improved webdav integration for one-click editing office documents; fixed sanitizing attachemnt names during upload using the standard mechanism again; removed (optional) dependency on FlexPaperPlugin (flash) in favour of DocumentViewerPlugin (html5); fixed url construction in javascript land; add support for JQPhotoSwipeContrib, a much nicer lightbox image preview; added support for LikePlugin to rate attachments; replaced famfamfam icons with fontawsome ones; added registry entry to use register LibreOffice to be used for one-click edits on windows
11 Oct 2016:	using jquery-i18n for translations now
17 Jul 2015:	added support for Foswiki-2.0; added support for Foswiki:Extensions/WebDAVContrib
16 Dec 2014:	add support for Foswiki:Extensions/MediaElementPlugin to preview audio and video attachments
29 Aug 2014:	fully specify rest security
28 May 2014:	improve performance on bulk operations on attachments; fixed tooltip poping up automatically
04 Apr 2014:	flag rest handlers that don't require authentication
18 Mar 2014:	render correct form data when displaying an old revision
20 Feb 2014:	fixed permission checking of actions; added one-click editing of office documents
08 Jan 2014:	fixed file corruption under Windows; fixed too aggressive renaming of files during upload
12 Dec 2013:	fixed initialization of defaults
07 Nov 2013:	fixed malformed JSON on some remote procedures
01 Nov 2013:	have a checkbox in the properties dialog to mark an image attachment to be used as a thumbnail in search results; better support for WebDavContrib: one-click edit of office attachments; jslinting javascript code (excluding 3rd party upstream code)
08 Apr 2013:	fixed html error
14 Mar 2013:	default to chunked upload; fixed handling of attachments with commas in their name
01 Feb 2013:	fixed error handling; hiding access to edit actions when not authorized anyway; fixed uploading files with special chars in their name; fixed initialization of flash backend; fixed reading foswiki preference settings; fixed uploading files with commas in their name
31 Jan 2013:	using ATTACHLINKBOX to control the default state of the "create link" checkbox
25 Jan 2013:	fixed auto-start feature; fixed registration of uploader component
18 Jan 2013:	improved compatibility with PatternSkin; fixed configure barfing on an undef value
24 Sep 2012:	updated to latest plupload version; allow to add arbitary properties, not only comments, createlink, hide-file flags
10 Jul 2012:	replaced all simplemodals with jquery-ui dialogs; added nullformat,nullheader,nullfooter to %ATTACHMENTS macro; removed dependency on WebDAVLinkPlugin to render webdav-enabled urls
08 May 2012:	fixed silent dependency on DBCachePlugin; fixed integration with PatternSkin; fixed dependency on Foswiki:Extensions/RenderPlugin; fixed interaction with Foswiki:Extensions/MetaCommentPlugin
26 Apr 2012:	initial release