%META:TOPICINFO{author="TWikiContributor" date="1587864235" format="1.1" version="$Rev$"}%
---+!! Upload to TWiki Add-On
<!--
   Contributions to this TWiki add-on are appreciated. Please update the add-on page at
   https://twiki.org/cgi-bin/view/Plugins/UploadToTWikiAddOn or provide feedback at
   https://twiki.org/cgi-bin/view/Plugins/UploadToTWikiAddOnDev.
   If you are a TWiki contributor please update the add-on in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Introduction

This is a small Perl script to programmatically attach a file to any TWiki topic. The script can be executed on any computer, it does not have to be on the server where TWiki is installed. This script i useful to create mashups of TWiki and other applications.

The script is typically called from another script. As an actual use case, this script was used to attach audio voice files from voice mails to project pages in a TWiki application.

---++ Usage

To attach a file to a TWiki topic, type this on the command line:
<verbatim>
./uploadtotwiki.pl -l <login> -c <comment> <file(s)> <TWiki URL>
</verbatim>
and enter the password when prompted.

Supported command line parameters:
   * =-l login      -= login name of TWiki account (optional)
   * =-p password   -= password of TWiki account (optional)
   * =-c 'comment'  -= comment of attached file (default: 'Uploaded by uploadtotwiki/2011-01-12')
   * =-h 1          -= hide attachment, 0 or 1 (default: 0)
   * =-i 1          -= inline attachment, e.g create link in topic text (default: 0)
   * =-d 60         -= delay in seconds between uploads of multiple files (default: 15)
   * =file(s)       -= one or more local files to upload (required)
   * =URL           -= view URL of TWiki topic, http or https protocol (required, must be last)

Example:

=% ./uploadtotwiki.pl -l <nop>%USERNAME% ./smile.gif <nop>https://twiki.org/cgi-bin/view/Sandbox/UploadTest= %BR%
=Uploading ./smile.gif to <nop>https://twiki.org/cgi-bin/view/Sandbox/UploadTest= %BR%
=Enter password for <nop>%USERNAME% at twiki.org:= %BR%
=... upload finished.= %BR%
=%=

---++ Add-On Installation Instructions

__Note:__ This is a command line tool for administrators; regular TWiki user can ignore this.

   * Download the ZIP file from the Add-on Home (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Add-on topic |
     | ==tools/uploadtotwiki.pl== | Add-on script |
   * If inclined, move =uploadtotwiki.pl= to a different location or server
   * Run above example to test if the installation was successful
   * Install CPAN:LWP if missing (see [[https://twiki.org/cgi-bin/view/TWiki/HowToInstallCpanModules][CPAN instructions]])

---++ Limitations

   * At this time the script only supports !ApacheLogin only; support for !TemplateLogin is pending.
   * Upload of files fail silently (without error message) if:
      * the file name has unsupported characters (=$=, =@=, =^=, space, etc). Workaround: Rename files before upload.
      * the CSRF protection flag is set in configure. Workaround: Disable ={CryptToken}{Enable}= configure setting.
      * the user has no permission to update the topic.

---++ Add-On Info

   * Set SHORTDESCRIPTION = Script to programmatically attach a file to any TWiki topic

|  Add-on Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2007-2020, Peter Thoeny, [[https://twiki.org/][TWiki.org]], <br /> &copy; 2007-2020 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[https://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Add-on Version: | uploadtotwiki/2020-04-25 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2020-04-25: | TWikibug:Item7851: Small doc fixes: Proper TWiki.org links |
|  2018-07-10: | TWikibug:Item7841: Copyright update to 2018 |
|  2016-01-22: | TWikibug:Item7708: Copyright update to 2016 |
|  2015-05-29: | TWikibug:Item7604: Switch from GPL v2 to v3 |
|  2012-11-24: | TWikibug:Item6961: Doc improvements |
|  2011-07-10: | TWikibug:Item6725: Adding build stuff |
|  2011-01-12: | TWikibug:Item6530: Doc improvements |
|  2007-02-12: | Added =-l=, =-p=, =-c=, =-h=, =-i=, =-d= parameters; support for multiple files |
|  2007-02-11: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 (TWiki 4.0) |
|  CPAN Dependencies: | LWP |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  Add-on Home: | https://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | https://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | https://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topic:__ %SYSTEMWEB%.TWikiAddOns
