From: <de...@de...> - 2014-01-31 10:05:09
|
Author: PeterThoeny Date: 2014-01-31 04:05:02 -0600 (Fri, 31 Jan 2014) New Revision: 26976 Trac url: http://develop.twiki.org/trac/changeset/26976 Modified: twiki/branches/TWikiRelease06x00/EcoTrashPlugin/data/TWiki/EcoTrashPlugin.txt Log: Item7422: Initial version of EcoTrashPlugin - doc fixes Modified: twiki/branches/TWikiRelease06x00/EcoTrashPlugin/data/TWiki/EcoTrashPlugin.txt =================================================================== --- twiki/branches/TWikiRelease06x00/EcoTrashPlugin/data/TWiki/EcoTrashPlugin.txt 2014-01-31 10:04:39 UTC (rev 26975) +++ twiki/branches/TWikiRelease06x00/EcoTrashPlugin/data/TWiki/EcoTrashPlugin.txt 2014-01-31 10:05:02 UTC (rev 26976) @@ -1,73 +1,85 @@ -%META:TOPICINFO{author="TWikiContributor" date="1390792588" format="1.1" version="$Rev$"}% -<!-- Copyright 2014 TImothe Litt. See EcoTrashPlugin for license --> +%META:TOPICINFO{author="TWikiContributor" date="1391162686" format="1.1" version="$Rev$"}% +<!-- Copyright 2014 Timothe Litt. See license --> ---+!! !EcoTrashPlugin +<!-- + Contributions to this plugin are appreciated. Please update the plugin page at + http://twiki.org/cgi-bin/view/Plugins/EcoTrashPlugin or provide feedback at + http://twiki.org/cgi-bin/view/Plugins/EcoTrashPluginDev. + If you are a TWiki contributor please update the plugin 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" depth="2" }% +</div></sticky> +%SHORTDESCRIPTION% Without this plugin, %WIKITOOLNAME% is, in some environments, an ecological disaster. -With it, %WIKITOOLNAME% is ecologically correct. (If only it had been a !SuperFund site...I'd be rich.) +With it, %WIKITOOLNAME% is ecologically correct. -%TOC% - ---++ Background -%WIKITOOLNAME% deletes files and attachments by moving them to the %TRASHWEB% web. %WIKITOOLNAME% does not provide -a mechanism to expunge deleted files from the %TRASHWEB% web. +%WIKITOOLNAME% deletes files and attachments by moving them to the %TRASHWEB% web. %WIKITOOLNAME% does not provide a mechanism to expunge deleted files from the %TRASHWEB% web. + This works well for environments where infinite history is desired. -However, this is a problem in several environments: +However, this can be a problem in the following circumstances: * Where policy requires history to be limited - * Where for users are concerned that a mistakenly-attached file (perhaps \ -with embarrassing content) may be retained forever + * Where users are concerned that a mistakenly-attached file (perhaps with embarrassing content) may be retained forever * Where disk space isn't an infinite resource Traditionally, %WIKITOOLNAME% specifies that management of the %TRASHWEB% web requires command line or FTP access. This is not always possible and is error-prone. The past advice -was to delete and rebuild the entire %TRASHWEB% web, but various policy condsideration led to +was to delete and rebuild the entire %TRASHWEB% web, but various policy considerations led to manual methods that left the %TRASHWEB% in inconsistent states. ---++ Features + !EcoTrashPlugin provides a means to manage the %TRASHWEB% web. It allows you to expunge -(permanently delete) topics and attachments from the%TRASHWEB% web. +(permanently delete) topics and attachments from the %TRASHWEB% web. -%ICON{warning}% expunging items is irreversible (at least, without recourse to system +%ICON{warning}% Expunging items is irreversible (at least, without recourse to system backup tapes). Please be sure that this is what you want to do. -The [[%TRASHWEB%.WebTrashManager][TrashManager]] topic, distributed with this plugin, provides a -graphical interface to the %TRASHWEB% web's contents. +The [[%TRASHWEB%.WebTrashManager][TrashManager]] topic, distributed with this plugin, provides a graphical interface to the %TRASHWEB% web's contents. -The =tools/ecotrashsweeper= script provides a periodic maintenance function for the %TRASHWEB% web, -which can also be invoked from the graphical interface. +The =tools/ecotrashsweeper= script provides a periodic maintenance function for the %TRASHWEB% web, which can also be invoked from the graphical interface. This includes deleting any empty directories in pub/Trash, and enforcing your site retention policy defined in the configuration. ---++ Documentation -%TWISTY{mode="div" showlink="Developer documentation" hidelink="Hide developer documentation" -showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%"}% -<!-- Note: TOC entries suppressed because when TWISTY is closed, browsers become confused --> ----++!! Syntax Rules - This documentation is for developers. +This documentation is for developers. +%TWISTY{ + mode="div" + showlink="Show details %ICONURL{toggleopen}%" + hidelink="Hide details %ICONURL{toggleclose}%" +}% + !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. +---+++ Configuration functions -!%TRASH{"maxage"}% Returns the maximum age parameter (maximum retention) from configure. +=%<nop>TRASH{"minage"}%= - returns the minimum age parameter (required retention) from configure. -!%TRASH{"expiretime"}% Returns the time (serial) when files expire (now - maxage). +=%<nop>TRASH{"maxage"}= - returns the maximum age parameter (maximum retention) from configure. -!%TRASH{"expiredate"}% Returns the date (string) when files expire (now - maxage). +=%<nop>TRASH{"expiretime"}= - returns the time (serial) when files expire (now - maxage). -!%TRASH{"group"}% Returns the user group authorized to use the interface by configure. +=%<nop>TRASH{"expiredate"}= - returns the date (string) when files expire (now - maxage). -!%TRASH{"protected"}% Returns the list of %TRASHWEB% web topics that are protected from deletion. +=%<nop>TRASH{"group"}= - returns the user group authorized to use the interface by configure. -!%TRASH{"attachtopic"}% Returns the name of the topic that holds deleted attachments from configure. +=%<nop>TRASH{"protected"}= - returns the list of %TRASHWEB% web topics that are protected from deletion. -!%TRASH{"icon"}% Returns an image tag for the application icon. +=%<nop>TRASH{"attachtopic"}= - returns the name of the topic that holds deleted attachments from configure. ----+++!! Topic utilities - !%TRASH{"topicmove" options}% ----++++!! Options - Options are specified in the usual format -- each option is of the form =name="value"=, where the quotes +=%<nop>TRASH{"icon"}% Returns an image tag for the application icon. + +---+++ Topic utilities + +=%<nop>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 %SYSTEMWEB%.FormatTokens: @@ -89,13 +101,15 @@ * $restore - Link to restore topic * $comment - Comment associated with attachment ----+++!! Attachment lists - !%TRASH{"listattachments" options...}% +---+++ Attachment lists -!%TRASH{"listunclaimed" options...}% +=%<nop>TRASH{"listattachments" _options..._ }%= ----++++!! Options - Options are specified in the usual format -- each option is of the form =name="value"=, where the quotes +=%<nop>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 %SYSTEMWEB%.FormatTokens: * $name - Filename @@ -124,14 +138,18 @@ 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 + +---+++ !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. + %ENDTWISTY% + ---++ !EcoTrashSweeper -The =tools/ecotrashsweeper= script performs automatic maintenance of the %TRASHWEB% web. It should be run by =cron= -under the webserver user. +The =tools/ecotrashsweeper= script performs automatic maintenance of the %TRASHWEB% web. It should be run by =cron= under the webserver user. + The script: * Locates any =pub/%TRASHWEB%= directories that don't correspond to a %TRASHWEB% topic. (This can occur \ due to previous manual management or system failure.) Empty directories are expunged. Otherwise, the \ @@ -146,12 +164,13 @@ * =-t=1= - When specified, the script runs normally, except that it does not delete anything. This should \ be used to verify that the script is configured correctly. -Note that the script deletes directory trees directory trees under the %TRASHWEB% web. If misconfigured, it \ +Note that the script deletes directory trees under the %TRASHWEB% web. If misconfigured, it \ can do a great deal of damage. A trial run with -t=1 is *strongly* recommended. The same functions are available from the graphical interface, which is a good way to do a trial run. ---++ Issues + * Subwebs may not work properly due to the limitations of the FILEATTACHMENT metadata. * Only the RCS database format is supported, because the storage API doesn't provide the necessary functions. * The !WatchlistPlugin is not informed of the final deletion of a topic. However, since links are not usually \ @@ -167,10 +186,12 @@ ---++ Installation and Configuration -__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 %WIKITOOLNAME% server. -%TWISTY{mode="div" showlink="Installation instructions" hidelink="Hide installation instructions" -showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%"}% +You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the %WIKITOOLNAME% server. +%TWISTY{ + mode="div" + showlink="Show details %ICONURL{toggleopen}%" + hidelink="Hide details %ICONURL{toggleclose}%" +}% __1. Plugin installation__ @@ -181,8 +202,10 @@ * Automated, works in most environments * Do a manual installation * If you don't trust automation, or have an unusual environment + %ICON{"tip"}% 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. + %JQTABPANE% %JQTAB{"Using Configure"}% * Click on this link: [[%SCRIPTURL%/configure%SCRIPTSUFFIX%][configure]] @@ -279,24 +302,34 @@ ---++ Plugin Info -| Plugin Author: | TWiki:Main.TimotheLitt | -| Copyright: | © 2014, TWiki:Main.TimotheLitt | -| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) | -| Plugin Version: | 2014-01-29 (V1.002) | -| Change History: | <!-- versions below in reverse order --> | -| 2014-01-29 | Use system date display formats, handle disabled plugin more gracefully. | -| 2014-01-28 | Change minage handling to be more prominent | -| 2014-01-27 | Work-around issue with newer !JQueryPlugin, fix !Webhome, !TWiki version, and plugin disabled issues | -| 2014-01-26 | More cleanup, incorporate feedback | -| 2014-01-21 | General cleanup, add deferred features | -| 2014-01-19 | Technology preview | -| Dependencies | %$DEPENDENCIES% | -| Perl Version: | 5.008 | -| [[TWiki:Plugins/Benchmark][Benchmarks]]: | %TWIKIWEB%.GoodStyle nn%, %TWIKIWEB%.FormattedSearch nn%, %TOPIC% nn% | -| Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% | -| Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev | -| Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal | + * One line description, shown in the TextFormattingRules topic: + * Set SHORTDESCRIPTION = Trash manager to restore or permanently delete topics and attachments (manually and automated) -__Related Topics:__ %TWIKIWEB%.TWikiPlugins, %TWIKIWEB%.DeveloperDocumentationCategory, %TWIKIWEB%.AdminDocumentationCategory +%TABLE{ tablewidth="100%" columnwidths="170," }% +| Plugin Author: | TWiki:Main.TimotheLitt | +| Copyright: | © 2014 TWiki:Main.TimotheLitt %BR% © 2014 TWiki:TWiki.TWikiContributor | +| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) | +| Plugin Version: | 2014-01-31 (V1.002) | +%TWISTY{ + mode="div" + showlink="Show Change History %ICONURL{toggleopen}%" + hidelink="Hide Change History %ICONURL{toggleclose}%" +}% +%TABLE{ tablewidth="100%" columnwidths="170," }% +| 2014-01-31 | Doc fixes -- TWiki:Main.PeterThoeny | +| 2014-01-29 | Use system date display formats, handle disabled plugin more gracefully. | +| 2014-01-28 | Change minage handling to be more prominent | +| 2014-01-27 | Work-around issue with newer !JQueryPlugin, fix !Webhome, !TWiki version, and plugin disabled issues | +| 2014-01-26 | More cleanup, incorporate feedback | +| 2014-01-21 | General cleanup, add deferred features | +| 2014-01-19 | Technology preview | +%ENDTWISTY% +%TABLE{ tablewidth="100%" columnwidths="170," }% +| Dependencies: | %$DEPENDENCIES% | +| Perl Version: | 5.008 | +| [[TWiki:Plugins/Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% | +| Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% | +| Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev | +| Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal | --- Main.TimotheLitt - 21Jan 2014 +__Related Topics:__ %TRASHWEB%.WebTrashManager, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory |