EcoTrashPlugin

EcoTrashPlugin itself provides supporting functions for the graphical interface. It is not intended for use in other topics, and may be changed without regard to compatibility with unauthorized applications.

Configuration functions

%TRASH{"minage"}% - returns the minimum age parameter (required retention) from configure.

%TRASH{"maxage"} - returns the maximum age parameter (maximum retention) from configure.

%TRASH{"expiretime"} - returns the time (serial) when files expire (now - maxage).

%TRASH{"expiredate"} - returns the date (string) when files expire (now - maxage).

%TRASH{"group"} - returns the user group authorized to use the interface by configure.

%TRASH{"protected"} - returns the list of Trash web topics that are protected from deletion.

%TRASH{"attachtopic"} - returns the name of the topic that holds deleted attachments from configure.

=%TRASH{"icon"}% Returns an image tag for the application icon.

Topic utilities

%TRASH{"topicmove" options... }%

Options

Options are specified in the usual format -- each option is of the form name="value", where the quotes are required. multiple options are separated by spaces. These accept several parameters:

• topic - Topic to format
• format - may contain the following special tokens in addition to the standard FormatTokens:
  • $name - Topic name
  • $rev - Version
  • $date - Date last modified (serial)
  • $fdate - Date last modified formatted for display
  • $user - User who last modified
  • $from - Moved from Web.Topic
    • $ftopic - Web.Topic
    • $fname - Web.Topic
  • $to - Moved to Web.Topic
    • $ttopic - Web.Topic
    • $tname - Web.Topic
    • $tpath -path from Trash
  • $mdate - Date of move (serial)
  • $fmdate - Date of move formatted for display
  • $mname - Name of user who moved
  • $restore - Link to restore topic
  • $comment - Comment associated with attachment

Attachment lists

%TRASH{"listattachments" options... }%

%TRASH{"listunclaimed" options... }%

Options

Options are specified in the usual format -- each option is of the form name="value", where the quotes are required. multiple options are separated by spaces. These accept several parameters:

• format - may contain the following special tokens in addition to the standard FormatTokens:
  • $name - Filename
  • $rev - Version
  • $path - Path supplied at attach
  • $size - File size
  • $date - Date last modified (serial)
  • $fdate - Date last modified formatted for display
  • $user - User who last modified
  • $attr - Attributes
  • $from - Moved from Web.Topic.filename
    • $ftopic - Web.Topic
    • $fname - filename
  • $to - Moved to Web.Topic.filename
    • $ttopic - Web.Topic
    • $tname - filename
    • $tpath -path from Trash
  • $mdate - Date of move (serial)
  • $fmdate - Date of move formatted for display
  • $mname - Name of user who moved
  • $restore - Link to restore attachment
  • $comment - Comment associated with attachment
• none - specifies a string to be produced if no items are found. The standard format tokens may be used.
• header - specifies a string to be produced if at least one item is found. The standard format tokens may be used.
• footer - specifies a string to be produced if at least one item is found. The standard format tokens may be used.

Note that date/time values are provided as time serial (integer) values or as a date string formatted according to the system-wide {DefaultDateFormat} and {DisplayTimeValues} configuration parameters. To obtain the time, use %CALC%'s $FORMATTIME on the integer.

TrashManager GUI

The GUI topic does some handstands to minimize the chance of it being treated as an editable topic. If you're a maintainer, and you really know what you're doing, click the trashcan icon to access the usual topic editing tools.

1. Plugin installation

There are three methods available for installing this plugin.:

• Use the configure script's extension manager.
  • Simplest, but your webserver must have write access to the TWiki code.
• Run the installation script manually
  • Automated, works in most environments
• Do a manual installation
  • If you don't trust automation, or have an unusual environment

No matter which method you choose, if you run selinux you will probably have to correct security context assignments for the new files and/or any intermediate directories.

Using Configure

• Click on this link: configure
• Click on Extensions, Find more extensions
• Locate EcoTrashPlugin
• Click on the link and follow the directions

Runing the installation script manually

From your TWiki root directory:

• Download the EcoTrashPlugin_installer script and the EcoTrashPlugin.md5 file from the Plugin Home (see below)
• Verify that the files were downloaded correctly: md5sum -c EcoTrashPlugin.md5
• Run the installer: perl EcoTrashPlugin_installer *

Manual installation

Install the prerequisite plugins. Be sure that they are at or above the minimum requred revisions.

Download the EcoTrashPlugin.zip or EcoTrashPlugin.tar.gz and EcoTrashPlugin.md5 files from the Plugin Home (see below)

Verify that the files were downloaded correctly: md5sum -c EcoTrashPlugin.md5

Expand the file that you selected in your TWiki installation directory. Content:

Correct file ownership, permissions, (and selinux contexts) for your environment.

: by default, the tar and unzip commands will set the permissions of each directory to those in the archive. This can disrupt your wiki. This can be avoided by explicitly extracting each of the files.*

data/Trash/WebTrashManager.txt	User interface
data/Trash/WebHomeEcoTrashPlugin.txt	Updated home topic for Trash web (TWiki rev below 26952)
data/TWiki/EcoTrashPlugin.txt	Documentation
pub/TWiki/EcoTrashPlugin/trash-manager-500.png	Screenshot
pub/TWiki/EcoTrashPlugin/trash-manager.png	Screenshot
lib/TWiki/Plugins/EcoTrashPlugin.pm	Perl module
lib/TWiki/Plugins/EcoTrashPlugin/Core.pm	Perl module
lib/TWiki/Plugins/EcoTrashPlugin/Config.spec	Configuration data
templates/restoreattachment.tmpl	Restore attachment template
tools/ecotrashsweeper	Perl script

• Rename Trash.WebHome to TrashWebHome.old
• Rename Trash.WebHomeEcoTrashPlugin to Trash.WebHome
• You can expunge TrashWebHome.old with Trash Manager

2. Plugin configuration and testing

• Run the configure script to configure the plugin.
  • Ensure that the bin/rest script is enabled and configured for authentication. (This is part of a normal TWiki installation.)
  • Check the additional settings in the Extensions section, and change if the defaults are not suitable for your installation.
    • {Plugins}{EcoTrashPlugin}{AdminGroup} - Administrator group
    • {Plugins}{EcoTrashPlugin}{MinimumAge} - Minimum retention period
    • {Plugins}{EcoTrashPlugin}{MaximumAge} - Maximum retention period
    • Check the {Plugins}{EcoTrashPlugin}{Enabled} box, in the Plugins section.
• Optional: Configure your webserver to allow access to items in the Trash by your administrator(s). This is normally prohibited for all users to prevent abuse, but it may be useful to an administrator who is reviewing Trash contents..
• Visit the TrashManager topic and verify that the plugin is active. If you have items in Trash but the presentation looks wrong, you probably have an old version of SpreadSheetPlugin. Please upgrade it.

We recommend that you install a crontab entry (or equivalent) for tools/ecotrashsweeper to run under the webserver user. This will enable automatic maintenance of the Trash web.

Because the script deletes files and directories, it is important to verify that it is configured correctly. We strongly recommend running it initially with the -t=1 option to verify that it is accessing the expected directories. This will do everything except the actual deletions. (It will produce messages indicating that deletions happen - but they don't.)

You can test the script from the TrashManager topic by clicking Test mode and Perform Maintenance Now. This will perform the exact actions that the maintenance script will with -t=1, displaying the results in your browser.

If you prefer not to set up a cron job, you can run the maintenance function from the TrashManager topic. If you elect that option, you can skip the rest of this section.

For a manual test run from the command line (on unix), use:

(cd /var/www/twiki; nice sudo -u *apache* perl -T -I bin tools/ecotrashsweeper -t=1)

Replace *apache* with the user under which the TWiki webserver runs on your system. It is important to use the webserver user so that updated files will have the correct permissions.

Once you are comfortable that the script is accessing the correct directories, you should set up a crontab entry for the webserver user.

A typical crontab entry looks like:

23 00 * * * (cd /var/www/twiki; nice perl  -T -I bin tools/ecotrashsweeper -q=1)

By default, the script will report every action. To suppress this, use the -q=1 switch.

For a log, use:

23 00 * * * (cd /var/www/twiki; nice perl  -T -I bin tools/ecotrashsweeper >>/var/www/twiki/data/ecotrashsweeper.log)

A somewhat simpler (equivalent) command structure on systems where perl scripts can be executed directly is:

(cd /var/www/twiki/bin; nice ../tools/ecotrashsweeper -q=1)