Difference: WatchlistPlugin (1 vs. 4)

Revision 42018-07-10 - TWikiContributor

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
   http://twiki.org/cgi-bin/view/Plugins/WatchlistPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Page contents

Introduction
User Interface
Syntax Rules
Watchlist Template
Installation & Configuration
Plugin Info

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

Introduction

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. To reduce noise, a user is not notified if he or she changes a topic on his or her watchlist.

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 / Unwatch 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 based on their WikiWord name, 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.

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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

Parameter	Description	Default
`"..."` or `action="..."`	Action to take	`"showwatchlink"`
Action: "showwatchlink"		Default
`"showwatchlink"`	Action: Show "Watch" / "Unwatch" link
`format="..."`	Format of link. Supported variables: • `$url` - URL to toggle the watch state. • `$watch` - "Watch" if page is not watched, else "Unwatch".	`"[[$url][$watch]]"`
Action: "showwatchlistlink"		Default
`"showwatchlistlink"`	Action: Show link of a user's watchlist topic
`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]]"`
`wikiname="..."`	WikiName of user	logged-in user
Action: "togglewatch"		Default
`"togglewatch"`	Action: Toggle the watch state of a topic. The URL parameter `watchlist_topic` must specify the `Web.TopicName`.
Action: "showchanges"		Default
`"showchanges"`	Action: Show watchlist changes of topics a user is watching
`header="..."`	Header of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesHeader}`
`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.	`{ChangesFormat}`
`footer="..."`	Footer of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesFooter}`
`separator="..."`	Separator between entries. Supported variable: • `$n` or `$n()` - newline.	`"$n"`
`limit="..."`	Limit number of topics.	URL parameter `limit` or `"50"`
`empty="..."`	Message shown if no topics are watched. Supported variable: • `$percnt` - percent sign.	`{EmptyMessage}`
Action: "watched"		Default
`"watched"`	Action: Show table of with all watched topics, with checkboxes to unwatch topics. The form action points to the "updatelist" action.
`topics="..."`	List of watched topics in `Web.TopicName` format. The plugin stores the watchlist using this variable action in the user's watchlist topic.	`""`
Action: "updatelist"		Default
`"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`.
Action: "preferences"		Default
`"preferences"`	Action: Show a form with preferences options. The form action points to the "updatepreferences" action.
`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"`
Action: "updatepreferences"		Default
`"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`.

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.

<--/twistyPlugin-->

Watchlist Template

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

Show details

Hide details

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

<--/twistyPlugin-->

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.

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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.

Added:

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

<--/twistyPlugin-->

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

Changed:

<
<

& TWiki:TWiki.TWikiContributor

>
>

& TWiki:TWiki.TWikiContributor

License:	GPL (GNU General Public License)
Sponsor:	Wave Systems Corp.

Changed:

<
<

Plugin Version:

2015-01-15

>
>

Plugin Version:

2018-07-10

Show Change History

Hide Change History

<--/twistyPlugin twikiMakeVisibleInline-->

Added:

>
>

2018-07-10:	TWikibug:Item7841: Copyright update to 2018
2018-07-05:	TWikibug:Item7703: Doc updates
2016-02-13:	TWikibug:Item7723: Fix for save of watchlist preference no longer working
2016-01-09:	TWikibug:Item7708: Copyright update to 2016
2015-11-29:	TWikibug:Item7699: Fix for unquoted string "useful" in apache error log

2015-01-15:	TWikibug:Item7607: Use TWiki API instead of internal function to space out topic name for title (code cleanup); switch from GPL v2 to v3
2014-10-08:	TWikibug:Item7571: Fix bug where immediate notification no longer works (bug introduced 2014-02-06)
2014-05-20:	TWikibug:Item7411: In list of webs, exclude webs the current user has no view access
2014-05-19:	TWikibug:Item7495: Execute bit missing in tools/watchlistnotify; doc fix
2014-04-30:	TWikibug:Item7411: Layout improvements in watchlist topic; doc fixes
2014-02-06:	TWikibug:Item7411: Improve caching, correct order of change processing, fix table alignment, add watch all topics in web and watch new topics in web, apply perltidy, report last change date in verbose watchlistnotify, make watchlistnotify run under 4.x, fix for mod_perl & mod_perl-masked environment -- TWiki:Main.TimotheLitt
2014-01-16:	TWikibug:Item7409: Don't notify oneself -- TWiki:Main.TimotheLitt
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

<--/twistyPlugin-->

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

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"

Revision 32015-01-15 - TWikiContributor

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
   http://twiki.org/cgi-bin/view/Plugins/WatchlistPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Page contents

Introduction
User Interface
Syntax Rules
Watchlist Template
Installation & Configuration
Plugin Info

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

Introduction

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 / Unwatch 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 based on their WikiWord name, 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.

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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

Parameter	Description	Default
`"..."` or `action="..."`	Action to take	`"showwatchlink"`
Action: "showwatchlink"		Default
`"showwatchlink"`	Action: Show "Watch" / "Unwatch" link
`format="..."`	Format of link. Supported variables: • `$url` - URL to toggle the watch state. • `$watch` - "Watch" if page is not watched, else "Unwatch".	`"[[$url][$watch]]"`
Action: "showwatchlistlink"		Default
`"showwatchlistlink"`	Action: Show link of a user's watchlist topic
`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]]"`
`wikiname="..."`	WikiName of user	logged-in user
Action: "togglewatch"		Default
`"togglewatch"`	Action: Toggle the watch state of a topic. The URL parameter `watchlist_topic` must specify the `Web.TopicName`.
Action: "showchanges"		Default
`"showchanges"`	Action: Show watchlist changes of topics a user is watching
`header="..."`	Header of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesHeader}`
`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.	`{ChangesFormat}`
`footer="..."`	Footer of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesFooter}`
`separator="..."`	Separator between entries. Supported variable: • `$n` or `$n()` - newline.	`"$n"`
`limit="..."`	Limit number of topics.	URL parameter `limit` or `"50"`
`empty="..."`	Message shown if no topics are watched. Supported variable: • `$percnt` - percent sign.	`{EmptyMessage}`
Action: "watched"		Default
`"watched"`	Action: Show table of with all watched topics, with checkboxes to unwatch topics. The form action points to the "updatelist" action.
`topics="..."`	List of watched topics in `Web.TopicName` format. The plugin stores the watchlist using this variable action in the user's watchlist topic.	`""`
Action: "updatelist"		Default
`"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`.
Action: "preferences"		Default
`"preferences"`	Action: Show a form with preferences options. The form action points to the "updatepreferences" action.
`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"`
Action: "updatepreferences"		Default
`"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`.

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.

<--/twistyPlugin-->

Watchlist Template

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

Show details

Hide details

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

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:

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

<--/twistyPlugin-->

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.

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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:

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.

<--/twistyPlugin-->

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

Changed:

<
<

& TWiki:TWiki.TWikiContributor

>
>

& TWiki:TWiki.TWikiContributor

License:	GPL (GNU General Public License)
Sponsor:	Wave Systems Corp.

Changed:

<
<

Plugin Version:

2014-05-20

>
>

Plugin Version:

2015-01-15

Show Change History

Hide Change History

<--/twistyPlugin twikiMakeVisibleInline-->

Added:

>
>

2015-01-15:	TWikibug:Item7607: Use TWiki API instead of internal function to space out topic name for title (code cleanup); switch from GPL v2 to v3
2014-10-08:	TWikibug:Item7571: Fix bug where immediate notification no longer works (bug introduced 2014-02-06)

2014-05-20:	TWikibug:Item7411: In list of webs, exclude webs the current user has no view access
2014-05-19:	TWikibug:Item7495: Execute bit missing in tools/watchlistnotify; doc fix
2014-04-30:	TWikibug:Item7411: Layout improvements in watchlist topic; doc fixes
2014-02-06:	TWikibug:Item7411: Improve caching, correct order of change processing, fix table alignment, add watch all topics in web and watch new topics in web, apply perltidy, report last change date in verbose watchlistnotify, make watchlistnotify run under 4.x, fix for mod_perl & mod_perl-masked environment -- TWiki:Main.TimotheLitt
2014-01-16:	TWikibug:Item7409: Don't notify oneself -- TWiki:Main.TimotheLitt
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

<--/twistyPlugin-->

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

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"

Revision 22014-05-20 - TWikiContributor

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
   http://twiki.org/cgi-bin/view/Plugins/WatchlistPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Page contents

Introduction
User Interface
Syntax Rules
Watchlist Template
Installation & Configuration
Plugin Info

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

Introduction

Changed:

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

>
> 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. To reduce noise, a user is not notified if he or she changes a topic on his or her watchlist.

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

Changed:

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

>
> Each user has a <WikiName>Watchlist topic in the Main web based on their WikiWord name, 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.

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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

Parameter	Description	Default
`"..."` or `action="..."`	Action to take	`"showwatchlink"`
Action: "showwatchlink"		Default
`"showwatchlink"`	Action: Show "Watch" / "Unwatch" link
`format="..."`	Format of link. Supported variables: • `$url` - URL to toggle the watch state. • `$watch` - "Watch" if page is not watched, else "Unwatch".	`"[[$url][$watch]]"`
Action: "showwatchlistlink"		Default
`"showwatchlistlink"`	Action: Show link of a user's watchlist topic
`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]]"`
`wikiname="..."`	WikiName of user	logged-in user
Action: "togglewatch"		Default
`"togglewatch"`	Action: Toggle the watch state of a topic. The URL parameter `watchlist_topic` must specify the `Web.TopicName`.
Action: "showchanges"		Default
`"showchanges"`	Action: Show watchlist changes of topics a user is watching
`header="..."`	Header of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesHeader}`
`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.	`{ChangesFormat}`
`footer="..."`	Footer of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesFooter}`
`separator="..."`	Separator between entries. Supported variable: • `$n` or `$n()` - newline.	`"$n"`
`limit="..."`	Limit number of topics.	URL parameter `limit` or `"50"`
`empty="..."`	Message shown if no topics are watched. Supported variable: • `$percnt` - percent sign.	`{EmptyMessage}`
Action: "watched"		Default
`"watched"`	Action: Show table of with all watched topics, with checkboxes to unwatch topics. The form action points to the "updatelist" action.
`topics="..."`	List of watched topics in `Web.TopicName` format. The plugin stores the watchlist using this variable action in the user's watchlist topic.	`""`
Action: "updatelist"		Default
`"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`.
Action: "preferences"		Default
`"preferences"`	Action: Show a form with preferences options. The form action points to the "updatepreferences" action.
`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"`
Action: "updatepreferences"		Default
`"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`.

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.

<--/twistyPlugin-->

Watchlist Template

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

Show details

Hide details

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

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:

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

<--/twistyPlugin-->

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.

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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:

Changed:

<
< 00 01 * * * (cd /var/www/twiki/tools; nice ../tools/watchlistnotify >/var/www/twiki/data/watchlistnotify-log.txt 2>&1)

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

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.

<--/twistyPlugin-->

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

Changed:

<
<

& TWiki:TWiki.TWikiContributor

>
>

& TWiki:TWiki.TWikiContributor

License:	GPL (GNU General Public License)
Sponsor:	Wave Systems Corp.

Changed:

<
<

Plugin Version:

2013-09-15

>
>

Plugin Version:

2014-05-20

Show Change History

Hide Change History

<--/twistyPlugin twikiMakeVisibleInline-->

Added:

>
>

2014-05-20:	TWikibug:Item7411: In list of webs, exclude webs the current user has no view access
2014-05-19:	TWikibug:Item7495: Execute bit missing in tools/watchlistnotify; doc fix
2014-04-30:	TWikibug:Item7411: Layout improvements in watchlist topic; doc fixes
2014-02-06:	TWikibug:Item7411: Improve caching, correct order of change processing, fix table alignment, add watch all topics in web and watch new topics in web, apply perltidy, report last change date in verbose watchlistnotify, make watchlistnotify run under 4.x, fix for mod_perl & mod_perl-masked environment -- TWiki:Main.TimotheLitt
2014-01-16:	TWikibug:Item7409: Don't notify oneself -- TWiki:Main.TimotheLitt

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

<--/twistyPlugin-->

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

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"

Revision 12013-09-15 - TWikiContributor

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
   http://twiki.org/cgi-bin/view/Plugins/WatchlistPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Page contents

Introduction
User Interface
Syntax Rules
Watchlist Template
Installation & Configuration
Plugin Info

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

Introduction

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

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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

Parameter	Description	Default
`"..."` or `action="..."`	Action to take	`"showwatchlink"`
Action: "showwatchlink"		Default
`"showwatchlink"`	Action: Show "Watch" / "Unwatch" link
`format="..."`	Format of link. Supported variables: • `$url` - URL to toggle the watch state. • `$watch` - "Watch" if page is not watched, else "Unwatch".	`"[[$url][$watch]]"`
Action: "showwatchlistlink"		Default
`"showwatchlistlink"`	Action: Show link of a user's watchlist topic
`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]]"`
`wikiname="..."`	WikiName of user	logged-in user
Action: "togglewatch"		Default
`"togglewatch"`	Action: Toggle the watch state of a topic. The URL parameter `watchlist_topic` must specify the `Web.TopicName`.
Action: "showchanges"		Default
`"showchanges"`	Action: Show watchlist changes of topics a user is watching
`header="..."`	Header of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesHeader}`
`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.	`{ChangesFormat}`
`footer="..."`	Footer of watchlist changes. Supported variable: • `$n` or `$n()` - newline.	`{ChangesFooter}`
`separator="..."`	Separator between entries. Supported variable: • `$n` or `$n()` - newline.	`"$n"`
`limit="..."`	Limit number of topics.	URL parameter `limit` or `"50"`
`empty="..."`	Message shown if no topics are watched. Supported variable: • `$percnt` - percent sign.	`{EmptyMessage}`
Action: "watched"		Default
`"watched"`	Action: Show table of with all watched topics, with checkboxes to unwatch topics. The form action points to the "updatelist" action.
`topics="..."`	List of watched topics in `Web.TopicName` format. The plugin stores the watchlist using this variable action in the user's watchlist topic.	`""`
Action: "updatelist"		Default
`"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`.
Action: "preferences"		Default
`"preferences"`	Action: Show a form with preferences options. The form action points to the "updatepreferences" action.
`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"`
Action: "updatepreferences"		Default
`"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`.

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.

<--/twistyPlugin-->

Watchlist Template

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

Show details

Hide details

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

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:

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

<--/twistyPlugin-->

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.

Show details

Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

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

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.

<--/twistyPlugin-->

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

Show Change History

Hide Change History

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

<--/twistyPlugin-->

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

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"

View topic | History: r4 < r3 < r2 < r1 | More topic actions...

Copyright © 1999-2025 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.