Watchlist Plugin

The WatchlistPlugin handles the %WATCHLIST{...}% variable. All watchlist interaction is done using this variable.

Notes:

• Default values indicated by {...} are abbreviated configure settings. For example {ChangesFormat} is the {Plugins}{WatchlistPlugin}{ChangesFormat} configure setting.
• The plugin takes also action on a watchlist_action URL parameter. If present, one of the above actions are taken.

This plugin has a WatchlistTemplate topic and two e-mail templates.

1. WatchlistTemplate:

The WatchlistTemplate topic is used as a template for user watchlist topics. It contains a tab interface with three tabs showing the recent changes, the watchlist topics, and the preferences.

2. watchlistdigestnotify.tmpl:

The watchlistdigestnotify.tmpl template file is the e-mail template for digest notification. It is located in the twiki/templates directory. The plugin handles the TWiki variables, and in addition these special variables:

3. watchlistimmediatenotify.tmpl:

The watchlistimmediatenotify.tmpl template file is the e-mail template for immediate notification. It is located in the twiki/templates directory. The plugin handles the TWiki variables, and in addition these special variables:

1. Plugin Installation:

• For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.
  • See the installation supplement on TWiki.org for more information.

• 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.