RemoteFileAttachPlugin

Introduction

This plugin allows you to attach a remote file to a topic. Given an URL to a remote file it downloads the file and attaches it to a topic.

Syntax Rules

• Syntax: %REMOTEFILEATTACH{"url" name="..." overwrite="..."}
• Supported parameters:

  Parameter	Description	Default
  "URL"	The URL of the remote file to attach	none
  name="filenamename"	The name to use for the attachment.	A name based on the filename of the remote file. For example: if you specify "http://site.com/icon.jpg" as URL, the default name for the attachment will be "icon.jpg"
  overwrite="0" or overwrite="1"	When enabled: if an attachment with the same name already exists it will be overwritten (without asking)	0

• Syntax: %REMOTEFILEATTACH_MSG%
  The error message returned after executing %REMOTFILEATTACH{...}% (if an error occured).

Usage

When the URL is an empty string %REMOTEFILEATTACH{...}% will do nothing.

When %REMOTEFILEATTACH{...}% is processed and no error occured, the browser is redirected to the viewed topic with two URL parameters: remotefileattach and name. They can be used to test whether a file was succesfully attached and display the name of the attached file. They also flag the RemoteFileAttachPlugin so it doesn't try to attach the file again.

If an error occured, or the user tried to attach a file with a name which already exists (when overwrite=off) the browser is not redirected and = contains the error message or warning.

Important: use only one instance of %REMOTEFILEATTACH% per topic.

It is not recommended to hard-code the URL, because %REMOTEFILEATTACH% will try to attach the specified file everytime the topic is viewed. The URL should be specified based on some condition, for example an url-parameter. See the example-form below.

• Bad idea:
  %REMOTEFILLEATTACH{"http://site.com/file.zip" name="attach.zip"}%

• Good idea:
  %REMOTEFILEATTACH{"%URLPARAM{attachurl}%" name="attach.zip"}%

Note:

• Instead of using overwrite="1" you can also use overwrite="on" . This is easier when using a checkbox in a form.

Examples

• %REMOTEFILEATTACH{"http://www.mozilla.org/images/feature-logos1.png"}%
  Download the picture from the specified URL and attach it as feature-logos1.png

• %REMOTEFILEATTACH{"%URLPARAM{myurl}%" name="" overwrite="on"}%
  If an URL parameter myurl is specified, download it and attach it with the name specified in url parameter name. If the url parameter myurl isn't specified, do nothing. If the url parameter name is empty, yield an error. When an attachment with the given name already exists, overwrite it.

• %REMOTEFILEATTACH_MSG%
  Display the output from the last %REMOTEFILEATTACH% directive, if any, or display nothing.

• RemoteFileAttachExample contains a more extended example.

EXAMPLE: A simple upload form

Source of the example:

<form action='%TOPICURL%'> 
  %MAKETEXT{"URL of the file to attach:"}%
   <input class="twikiInputField" type="text" name="attachurl" size="32" />
   <input type="submit" class="twikiSubmit" value='%MAKETEXT{"Download and attach"}%' /> 
</form>

%REMOTEFILEATTACH{"%URLPARAM{attachurl}%"}%

%IF{"defined remotefileattach" then="<B>%URLPARAM{name}% successfully attached to topic.</B>"}%

<B>%REMOTEFILEATTACH_MSG%</B>

Possible Improvements

• Improve the mechanism which determines a filename based on the URL when no filename is specified. Maybe based on the Content-Type HTTP header?
• ...

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Download and attach remote files to topics

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

• Run configure for automated install, or do a manual install:
• Install the Perl module CPAN:LWP::Simple
• Download the ZIP file from the Plugin web (see below)
• Unzip RemoteFileAttachPlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/RemoteFileAttachPlugin.txt	Plugin topic
  data/TWiki/RemoteFileAttachExample.txt	Example topic
  lib/TWiki/Plugins/RemoteFileAttachPlugin.pm	Plugin Perl module

• Configure the Plugin:
  • Run the configure script to enable the plugin
• Test if the installation was successful:
  • Use the example upload form above.

Plugin Info

Plugin Author:	TWiki:Main.JosKunnekes
Copyright:	© 2007, TWiki:Main.JosKunnekes © 2007-2011 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2011-01-13
Change History:
2011-01-13:	TWikibug:Item6530: Doc improvements; changing TWIKIWEB to SYSTEMWEB -- TWiki:Main.PeterThoeny
26 Jun 2007:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	CPAN:LWP::Simple
Other Dependencies:	none
Perl Version:	5.005
Benchmarks:	GoodStyle 100%, FormattedSearch 100%, RemoteFileAttachPlugin 100% (*)
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/RemoteFileAttachPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/RemoteFileAttachPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/RemoteFileAttachPluginAppraisal

(*) When attaching a file the topic is rendered after the file is downloaded and attached. The delay depends on the size of the file and the connection speed of the hosts on both end of the transfer.

Related Topics: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences