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: |
tools/watchlistnotify | Command-line script for digest notification |
templates/watchlistimmediatenotify.tmpl | E-mail template for immediate notification |
templates/watchlistdigestnotify.tmpl | E-mail template for digest notification |
pub/TWiki/WatchlistPlugin/*png | Screenshots |
lib/TWiki/Plugins/WatchlistPlugin/Core.pm | Plugin core module |
lib/TWiki/Plugins/WatchlistPlugin/Config.spec | Configure spec file |
lib/TWiki/Plugins/WatchlistPlugin.pm | Plugin Perl module |
data/TWiki/WatchlistTemplate.txt | Template topic for watchlist topics |
data/TWiki/WatchlistPlugin.txt | Plugin topic |
- 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/tools; 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.
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:
