Difference: WatchlistPlugin ( vs. 1)

Revision 12013-09-15 - TWikiContributor

Line: 1 to 1

Watchlist Plugin

   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/WatchlistPlugin or provide feedback at
   If you are a TWiki contributor please update the plugin in the SVN repository.

Watch topics of interest and get notified of changes by e-mail


The WatchlistPlugin adds watchlist feature to TWiki topics. Topics of interest can be watched and unwatched. A user can see recent changes of all watched topics. A user can also subscribe to get e-mail notification of changes, either on each topic save, or in digest mode.

This plugin is intended to augment the MailerContrib with a point and click watch and subscribe feature. At a later point, the WatchlistPlugin will replace the MailerContrib, which operates on the not as easy to use WebNotify topics.

User Interface

This plugin adds a "Watch" link to the topic action row at the bottom of every TWiki topic. Once watched, one can "Unwatch" the topic.

It also adds a Watch Menu dropdown / Unwatch Menu dropdown pulldown menu to the top bar of the TopMenuSkin. This pulldown menu has a Watchlist Changes menu item to see recent changes of watched topics.

Each user has a <WikiName>Watchlist topic in the Main web, such as JimmyNeutronWatchlist. The topic has three tabs:

  • "Recent Changes" tab: Shows recent changes on all topics that are on the user's watchlist.
  • "Watched Topics" tab: Shows the list of topics the user is watching.
  • "Preferences" tab: Shows user's e-mail subscription preference, one of: None, Immediate, Digest.

Screenshot of "Recent Changes" tab:


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:


Syntax Rules

This section is for application developers who want to create custom watchlist integrations.

<--/twistyPlugin twikiMakeVisibleInline-->

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

<-- -->
Sorted descending
Description Default
wikiname="..." WikiName of user logged-in user
topics="..." List of watched topics in Web.TopicName format. The plugin stores the watchlist using this variable action in the user's watchlist topic. ""
separator="..." Separator between entries. Supported variable:
$n or $n() - newline.
notification="..." Notification preference: "n0" - none, "n1" immediate, "n2" digest. The plugin stores the notification preference using this variable action in the user's watchlist topic. "n0"
limit="..." Limit number of topics. URL parameter limit
or "50"
header="..." Header of watchlist changes. Supported variable:
$n or $n() - newline.
format="..." Format of link. Supported variables:
$url - URL to toggle the watch state.
$watch - "Watch" if page is not watched, else "Unwatch".
format="..." Format of link. Supported variables:
$url - URL of the watchlist topic. In case the topic does not exist, a special URL is returned so that the topic with the proper format can be created.
$wikiname - WikiName of user.
"[[$url][Watchlist Changes]]"
format="..." Format of one entry of watchlist changes. Supported variables:
$web - name of web.
$topic - topic name.
$title - topic title, or spaced topic name if title does not exist.
$date - change date of topic.
$rev - revision of topic.
$wikiname - WikiName of last author.
$percnt - percent sign.
$n or $n() - newline.
footer="..." Footer of watchlist changes. Supported variable:
$n or $n() - newline.
empty="..." Message shown if no topics are watched. Supported variable:
$percnt - percent sign.
Action: "watched" Default
Action: "updatepreferences" Default
Action: "updatelist" Default
Action: "togglewatch" Default
Action: "showwatchlistlink" Default
Action: "showwatchlink" Default
Action: "showchanges" Default
Action: "preferences" Default
"watched" Action: Show table of with all watched topics, with checkboxes to unwatch topics. The form action points to the "updatelist" action.  
"updatepreferences" Action: Update the watchlist preferences. The URL parameter watchlist_topic must specify the Web.TopicName of the topic to update. The URL parameter named notification indicates the new preference, one of n0, n1 or n2.  
"updatelist" Action: Update the watched topics list. The URL parameter watchlist_topic must specify the Web.TopicName of the topic to update. A list of URL parameters named watchlist_item represents the list of watched topics, each one of format Web.TopicName.  
"togglewatch" Action: Toggle the watch state of a topic. The URL parameter watchlist_topic must specify the Web.TopicName.  
"showwatchlistlink" Action: Show link of a user's watchlist topic  
"showwatchlink" Action: Show "Watch" / "Unwatch" link  
"showchanges" Action: Show watchlist changes of topics a user is watching  
"preferences" Action: Show a form with preferences options. The form action points to the "updatepreferences" action.  
"..." or
Action to take "showwatchlink"


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


Watchlist Template

This section is for site administrators who want to customize the watchlists.

<--/twistyPlugin twikiMakeVisibleInline-->

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:

Variable Expands to
%WATCHLISTTO% E-mail "To" list, comma-space separated
%WATCHCHANGESTEXT% The watchlist changes in text format. The format of a changes entry is defined by the {Plugins}{WatchlistPlugin}{NotifyTextFormat} configure setting
%WATCHLISTUSER% WikiName of user being notified

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:

Variable Expands to
%WATCHLISTTO% E-mail "To" list, comma-space separated
%WATCHLISTUSER% WikiName of user being notified
%WATCHWEB% Name of updated topic
%WATCHTOPIC% Name of updated web
%WATCHTITLE% Title of updated topic
%WATCHUSER% WikiName of last author of updated topic
%WATCHREV% Revision of updated topic
%WATCHDATE% Update date of of topic


Installation & Configuration

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 TWiki server.

<--/twistyPlugin twikiMakeVisibleInline-->

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/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

ALERT! 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%:

 "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"

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.


Plugin Info

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Watch topics of interest and get notified of changes by e-mail

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2013 Wave Systems Corp.
© 2013 TWiki:Main.PeterThoeny & TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Sponsor: Wave Systems Corp.
Plugin Version: 2013-09-15
<--/twistyPlugin twikiMakeVisibleInline-->
2013-04-11: TWikibug:Item7154: Minor doc fixes
2013-03-15: TWikibug:Item7215: Log watchlist changes & e-mail notification actions
2013-03-15: TWikibug:Item7143: Change default notification from "none" to "immediate"
2013-03-11: TWikibug:Item7143: Sanitize watchlist_topic parameter
2013-03-06: TWikibug:Item7143: Support new $title variable that expands to the topic title, or the spaced topic name if the title does not exist
2013-03-05: TWikibug:Item7143: The "showwatchlistlink" action now returns full URL instead of Web.Topic link so that it can be used in a a HTML tag.
2013-03-04: TWikibug:Item7143: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.2
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Plugin Benchmarks: GoodStyle nn%, FormattedSearch nn%, WatchlistPlugin nn%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/WatchlistPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/WatchlistPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/WatchlistPluginAppraisal

Related Topics: WatchlistTemplate, TWikiPlugins, UserDocumentationCategory, UserToolsCategory

META FILEATTACHMENT attachment="watchlist-changes-300.png" attr="h" comment="" date="1362433125" name="watchlist-changes-300.png" path="watchlist-changes-300.png" size="74283" user="TWikiContributor" version="1"
META FILEATTACHMENT attachment="watchlist-topics.png" attr="h" comment="" date="1362431924" name="watchlist-topics.png" path="watchlist-topics.png" size="44849" user="TWikiContributor" version="1"
META FILEATTACHMENT attachment="watchlist-changes.png" attr="h" comment="" date="1362431924" name="watchlist-changes.png" path="watchlist-changes.png" size="70951" user="TWikiContributor" version="1"
META FILEATTACHMENT attachment="watchlist-preferences.png" attr="h" comment="" date="1362431923" name="watchlist-preferences.png" path="watchlist-preferences.png" size="26434" user="TWikiContributor" version="1"
META FILEATTACHMENT attachment="watchlist-profile.png" attr="h" comment="" date="1362450432" name="watchlist-profile.png" path="watchlist-profile.png" size="163309" user="TWikiContributor" version="1"
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.WatchlistPlugin.