Allows users to "subscribe" to regularly scheduled e-mails containing either:

• A report on changes to all topics that have changed within a particular TWiki web.
• A report on changes to a specific topic or set of topics the user can define flexibly.
• The entire content of a specific topic or set of topics. This is referred to as "news mode."
• The companion plugin (TWiki:Plugins.SubscribePlugin) lets you trivially add a "Subscribe to changes" button to topics

<-- Included by WebChangesAlert -->

• Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as complete topics instead of change summaries. ! causes the topic to be mailed every time even if there have been no changes, and ? will mail the topic only if there have been changes to it. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

• You can use * in a topic name, where it is treated as a wildcard character. A * will match zero or more other characters - so, for example, Fred* will match all topic names starting with Fred, *Fred will match all topic names ending with Fred, and * will match all topic names.
• Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic". The '-' sign means "unsubscribe" or "don't send notifications regarding this particular topic". This allows users to elect to filter out certain topics. Topic filters ('-') take precedence over topic includes ('+') i.e. if you unsubscribe from a topic it will cancel out any subscriptions to that topic.
• Each topic may optionally be followed by an integer in parentheses, indicating the depth of the tree of children below that topic. Changes in all these children will be detected and reported along with changes to the topic itself. Note This uses the TWiki "Topic parent" feature.
• Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as complete topics instead of change summaries. ! causes the topic to be mailed every time even if there have been no changes, and ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions, and is intended for mailshotting regular newletters.

tools/mailnotify

In the above examples, topics is a space-separated list of topic names. The user may further customize the specific content they will receive using the following formats:

• Specify topics without a Web. prefix
• Topics must exist in this web.
• Topics may be specified using * wildcards
• Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic" (the same as not putting anything). The '-' sign means "unsubscribe" or "don't send notifications regarding this topic". This allows users to elect to filter out certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').

• Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as complete topics instead of change summaries. ! causes the topic to be mailed every time even if there have been no changes, ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions.

Note that when using the "news mode" ! or ? specifiers are used the entire topic text is mailed out as HTML. The newsletter template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.

In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected.

TWiki/Contrib/MailerContrib code library

package TWiki::Contrib::MailerContrib::WebNotify

ClassMethod new($web, $topic)

ObjectMethod writeWebNotify()

ObjectMethod getSubscriber($name, $noAdd)

• $name - Name of subscriber (wikiname with no web or email address)
• $noAdd - If false or undef, a new subscriber will be created for this name

ObjectMethod getSubscribers()

ObjectMethod subscribe($name, $topics, $depth)

• $name - Name of subscriber (wikiname with no web or email address)
• $topics - wildcard expression giving topics to subscribe to
• $depth - Child depth to scan (default 0)
• $mode - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.

ObjectMethod unsubscribe($name, $topics, $depth)

• $name - Name of subscriber (wikiname with no web or email address)
• $topics - wildcard expression giving topics to subscribe to
• $depth - Child depth to scan (default 0)

ObjectMethod stringify() -> string

ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)

• $change - ref of a TWiki::Contrib::Mailer::Change
• $db - TWiki::Contrib::MailerContrib::UpData database of parent references
• $changeSet - ref of a hash mapping emails to sets of changes
• $seenSet - ref of a hash recording indices of topics already seen
• $allSet - ref of a hash that maps topics to email addresses for news subscriptions

ObjectMethod processCompulsory($topic, $db, \%allSet)

• $topic - topic name
• $db - TWiki::Contrib::MailerContrib::UpData database of parent references
• \%allSet - ref of a hash that maps topics to email addresses for news subscriptions

ObjectMethod isEmpty() -> boolean

package TWiki::Contrib::MailerContrib::Subscriber

ClassMethod new($name)

• $name - Wikiname, with no web, or email address, of user targeted for notification

ObjectMethod getEmailAddresses() -> list

ObjectMethod subscribe($subs)

• $subs - Subscription object

ObjectMethod unsubscribe($subs)

• $subs - Subscription object

An unsubscription is a statement of the subscribers desire not to be notified of changes to this topic.

ObjectMethod isSubscribedTo($topic) -> $subscription

• $topic - Topic object we are checking
• $db - TWiki::Contrib::MailerContrib::UpData database of parents

ObjectMethod isUnsubscribedFrom($topic) -> $subscription

• $topic - Topic object we are checking
• $db - TWiki::Contrib::MailerContrib::UpData database of parents

ObjectMethod stringify() -> string

package TWiki::Contrib::MailerContrib::Subscription

ClassMethod new($pages, $childDepth, $news)

• $pages - Wildcarded expression matching subscribed pages
• $childDepth - Depth of children of $topic to notify changes for. Defaults to 0
• $mode - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.

ObjectMethod stringify() -> string

ObjectMethod matches($topic, $db, $depth) -> boolean

• $topic - Topic object we are checking
• $db - TWiki::Contrib::MailerContrib::UpData database of parent names
• $depth - If non-zero, check if the parent of the given topic matches as well. undef = 0.

ObjectMethod getMode() -> $mode

package TWiki::Contrib::MailerContrib::Change

ClassMethod new($web)

• $web - Web name
• $topic - Topic name
• $author - String author of change
• $time - String time of change
• $rev - Revision identifier

ObjectMethod merge($change)

• $change - Change record to merge

ObjectMethod expandHTML($html) -> string

• $html - Template to expand keys within

Returns the expanded template.

ObjectMethod expandPlain() -> string

package TWiki::Contrib::MailerContrib::UpData

ClassMethod new($web)

• $web - Web we are building parent relationships for

ObjectMethod getParent($topic) -> string

package TWiki::Contrib::Mailer

Package of support for extended WebNotify notification, supporting per-topic notification and notification of changes to children.

Also supported is a simple API that can be used to change the WebNotify topic from other code.

StaticMethod mailNotify($webs, $session, $verbose)

• $webs - filter list of names webs to process. Wildcards (*) may be used.
• $session - optional session object. If not given, will use a local object.
• $verbose - true to get verbose (debug) output

Main entry point.

Process the WebNotify topics in each web and generate and issue notification mails. Designed to be invoked from the command line; should only be called by mailnotify scripts.

Installation Instructions

• If you have TWiki 4.1 or later, and Perl 5.8, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • The webserver user has to have permission to write to all areas of your installation for this to work.
• If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
  • Just download the MailerContrib_installer perl script and run it.
• Notes:
  • The installer script will:
    • Automatically resolve dependencies,
    • Copy files into the right places in your local install (even if you have renamed data directories),
    • check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
    • If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
    • (Developers only: the script will look for twikiplugins/MailerContrib/MailerContrib.tgz before downloading from TWiki.org)
  • If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
    • Point the environment variable $TWIKI_PACKAGES to this directory, and the installer script will look there first for required TWiki packages.
      • $TWIKI_PACKAGES is actually a path; you can list several directories separated by :
    • If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror
• If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
  1. Download and unpack one of the .zip or .tgz archives to a temporary directory.
  2. Manually copy the contents across to the relevant places in your TWiki installation.

1. 1. Run configure and enable the module, if it is a plugin.
   2. Repeat from step 1 for any missing dependencies.

• To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.

Setting up your cron job(s)

Developer Notes

Contrib Info

Summary of Contents

tools/mailnotify

TWiki/Contrib/MailerContrib code library

Installation Instructions

Setting up your cron job

Settings

• Name of the perl package

Contrib Info