1. Plugin Installation:
- For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.
- Or, follow these manual installation steps:
- Download the ZIP file from the Plugins home (see below).
- Unzip
WatchlistPlugin.zip in your twiki installation directory. Content: | File: | Description: |
data/TWiki/WatchlistPlugin.txt | Plugin topic |
data/TWiki/WatchlistTemplate.txt | Template topic for watchlist topics |
pub/TWiki/WatchlistPlugin/*png | Screenshots |
templates/watchlistdigestnotify.tmpl | E-mail template for digest notification |
templates/watchlistimmediatenotify.tmpl | E-mail template for immediate notification |
lib/TWiki/Plugins/WatchlistPlugin.pm | Plugin Perl module |
lib/TWiki/Plugins/WatchlistPlugin/Core.pm | Plugin core module |
lib/TWiki/Plugins/WatchlistPlugin/Config.spec | Configure spec file |
tools/watchlistnotify | Command-line script for digest notification |
- Set the ownership of the extracted directories and files to the webserver user.
2. Plugin Configuration and Testing:
- Run the configure script and enable the plugin in the Plugins section.
- Configure additional plugin settings in the Extensions section if needed. Settings:
$TWiki::cfg{Plugins}{WatchlistPlugin}{ChangesFormat} # Format of one line of recently changed topics in the watchlist. Supported variables: $web: Name of web, $topic: Topic name, $title: Topic title, $date: Date of last change, $rev: Last revision number, $wikiname: WikiName of last user, $n or $n(): Newline.
$TWiki::cfg{Plugins}{WatchlistPlugin}{ChangesHeader} # Format of the header of the recently changed topic list. Supported variable: $n or $n(): Newline.
$TWiki::cfg{Plugins}{WatchlistPlugin}{ChangesFooter} # Format of the footer of the recently changed topic list. Supported variable: $n or $n(): Newline.
$TWiki::cfg{Plugins}{WatchlistPlugin}{EmptyMessage} # Text shown in the recent changes and watchlist topics screen if no topics are watched.
$TWiki::cfg{Plugins}{WatchlistPlugin}{NotifyTextFormat} # Format of one topic in the digest notification e-mail. Supported variables: $web: Name of web, $topic: Topic name, $title: Topic title, $date: Date of last change, $rev: Last revision number, $wikiname: WikiName of last user, $viewscript: URL of view script, $n: newline.
$TWiki::cfg{Plugins}{WatchlistPlugin}{AnchorName} # Anchor name to jump to after submit. Leave empty for no anchor jump.
$TWiki::cfg{Plugins}{WatchlistPlugin}{UseEmailField} # Use the "Email" form field of user profile topics instead of the e-mail stored in the password system. This is useful if LDAP authentication is used.
$TWiki::cfg{Plugins}{WatchlistPlugin}{Debug} # Debug plugin. See output in data/debug.txt
3. Configure Cron for Digest Notification:
You need to set up a
cron (or equivalent) job to run the
tools/watchlistnotify script. The script must be run as the webserver user and can be used as follows from the command-line:
$ cd /var/www/twiki/bin
$ ../tools/watchlistnotify
Change first to the twiki bin directory so that the script can find the TWiki libraries.
An optional
quiet=1 parameter can be specified to suppress progress output.
This example shows a crontab entry for user
apache on a RedHat or CentOS server that sends daily digest notification at 01:00, and logs the progress output:
00 01 * * * (cd /var/www/twiki/bin; nice ../tools/watchlistnotify >/var/www/twiki/data/watchlistnotify-log.txt 2>&1)
The tool can also be called from any directory if the twiki bin directory is specified. Example:
00 00 * * * cd /var/www/twiki/tools && perl -I /var/www/twiki/bin ./watchlistnotify quiet=1
Note: Multiple instances of the watchlistnotify script are not allowed to be executed simultaneously.
4. Upgrade the TopMenuSkin to get a "Watch" Pulldown Menu:
To show a "Watch" pulldown menu next to the "Edit" pulldown, upgrade the
TopMenuSkin to version 2013-02-26 or later, or add the following to
TopMenuSkinTopicMenu just before the
%STOPINCLUDE%:
%IF{
"context WatchlistPluginEnabled AND context authenticated"
then=" * $percntWATCHLIST{ \"showwatchlink\" format=\"<a href='$url' title='$watch this topic'>$watch %ICON{ "menu-down" format="<img src='$urlpath' width='$width' height='$height' border='0' alt='' />" }%</a>\" }$percnt
* $percntWATCHLIST{ \"showwatchlistlink\" format=\"[[$url][Watchlist Changes]]\" }$percnt"
else="<nop>"
}%
5. Upgrade the TWikiUserMappingContrib to get the "Watchlist Changes" box in the user profile topics:
To add the "Watchlist Changes" box to the user profile topics, upgrade the
TWikiUserMappingContrib to version 2013-02-26 or later, or update the
Main.UserProfileHeader to the latest version at
TWikisvn:TWikiUserMappingContrib/data/Main/UserProfileHeader.txt
.
6. Patch viewtopicactionbuttons to get a "Watch" Link in the Topic Action Row:
To add a "Watch" link to the bottom topic action row, edit
templates/viewtopicactionbuttons.tmpl and make the following two modifications.
1. In template definition
%TMPL:DEF{"topicactionbuttons"}%, add
%TMPL:P{"action_watch"}% before
%TMPL:P{"action_printable"}%.
2. Add the following two template definitions:
%TMPL:DEF{"action_watch"}%%TMPL:P{context="WatchlistPluginEnabled" then="watch_link" else=""}%%TMPL:END%
%TMPL:DEF{"watch_link"}%<span>%IF{ "context authenticated" then="$percntWATCHLIST{showwatchlink}$percnt" else="<strike>Watch</strike>" }%</span>%TMPL:P{"sep"}%%TMPL:END%
7. Test the Plugin:
Test if the installation was successful by watching and unwatching topics.
Make sure you watch changes of
other users, since you don't get mails for your own changes. If the plugin won't work, disable it in Configure, and than enable it again.
/ Unwatch 
Screenshot of "Watched Topics" tab:
Screenshot of "Preferences" tab:
The user profile pages have a "Watchlist Changes" box that shows recently changed topics the user is watching.
Screenshot of user profile:
