-# <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
+# <a name="Mailer Contrib"></a><a name=" Mailer Contrib"></a> Mailer Contrib
-Add-on to the TWiki kernel that allows users to "subscribe" to regularly scheduled e-mails containing either:
+[![](http://www.dementia.org/twiki//view/logo.gif)](http://wikiring.com)
+
+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
-**WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see [here](http://twiki.org/cgi-bin/view/Plugins/%TOPIC%?rev=1.17)**
+<div>WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/%TOPIC%?filename=%TOPIC%.zip&revInfo=1" target="_top">revision 17 of the zip</a>.</div>
<div>
<ul>
- <li><a href="#tools/mailnotify"> <code>tools/mailnotify</code></a></li>
- <li><a href="#TWiki/Contrib/_MailerContrib cod"> <code>TWiki/Contrib/MailerContrib</code> code library</a></li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::WebNotify</a><ul>
- <li><a href="#ClassMethod new($web, $topic)"> ClassMethod new($web, $topic)</a></li>
- <li><a href="#ObjectMethod write_WebNotify()"> ObjectMethod writeWebNotify()</a></li>
- <li><a href="#ObjectMethod getSubscriber($name"> ObjectMethod getSubscriber($name, $noAdd)</a></li>
- <li><a href="#ObjectMethod getSubscribers()"> ObjectMethod getSubscribers()</a></li>
- <li><a href="#ObjectMethod subscribe($name, $t"> ObjectMethod subscribe($name, $topics, $depth)</a></li>
- <li><a href="#ObjectMethod unsubscribe($name,"> ObjectMethod unsubscribe($name, $topics, $depth)</a></li>
- <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -> string</a></li>
- <li><a href="#ObjectMethod processChange($chan"> ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)</a></li>
- <li><a href="#ObjectMethod processCompulsory($"> ObjectMethod processCompulsory($topic, $db, \%allSet)</a></li>
- <li><a href="#ObjectMethod isEmpty() -> boolea"> ObjectMethod isEmpty() -> boolean</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Subscriber</a><ul>
- <li><a href="#ClassMethod new($name)"> ClassMethod new($name)</a></li>
- <li><a href="#ObjectMethod get_EmailAddresses("> ObjectMethod getEmailAddresses() -> list</a></li>
- <li><a href="#ObjectMethod subscribe($subs)"> ObjectMethod subscribe($subs)</a></li>
- <li><a href="#ObjectMethod unsubscribe($subs)"> ObjectMethod unsubscribe($subs)</a></li>
- <li><a href="#ObjectMethod is_SubscribedTo($to"> ObjectMethod isSubscribedTo($topic) -> $subscription</a></li>
- <li><a href="#ObjectMethod is_UnsubscribedFrom"> ObjectMethod isUnsubscribedFrom($topic) -> $subscription</a></li>
- <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -> string</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Subscription</a><ul>
- <li><a href="#ClassMethod new($pages, $childDe"> ClassMethod new($pages, $childDepth, $news)</a></li>
- <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -> string</a></li>
- <li><a href="#ObjectMethod matches($topic, $db"> ObjectMethod matches($topic, $db, $depth) -> boolean</a></li>
- <li><a href="#ObjectMethod getMode() -> $mode"> ObjectMethod getMode() -> $mode</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Change</a><ul>
- <li><a href="#ClassMethod new($web)"> ClassMethod new($web)</a></li>
- <li><a href="#ObjectMethod merge($change)"> ObjectMethod merge($change)</a></li>
- <li><a href="#ObjectMethod expandHTML($html) -"> ObjectMethod expandHTML($html) -> string</a></li>
- <li><a href="#ObjectMethod expandPlain() -> st"> ObjectMethod expandPlain() -> string</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::UpData</a><ul>
- <li><a href="#ClassMethod new($web)"> ClassMethod new($web)</a></li>
- <li><a href="#ObjectMethod getParent($topic) -"> ObjectMethod getParent($topic) -> string</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::Mailer"> package TWiki::Contrib::Mailer</a><ul>
- <li><a href="#StaticMethod mailNotify($webs, $"> StaticMethod mailNotify($webs, $session, $verbose)</a></li>
- </ul>
- </li>
+ <li><a href="#tools/mailnotify"> tools/mailnotify</a></li>
+ <li><a href="#TWiki/Contrib/_MailerContrib cod"> TWiki/Contrib/MailerContrib code library</a></li>
<li><a href="#Installation Instructions"> Installation Instructions</a><ul>
<li><a href="#Setting up your cron job(s)"> Setting up your cron job(s)</a></li>
</ul>
</ul>
</div>
-# <a name="tools/mailnotify"></a> `tools/mailnotify`
+## <a name="tools/mailnotify"></a> tools/mailnotify
-The central component of [[MailerContrib]] is a script, `tools/mailnotify`, that generates and sends out the emails based on analysis of
+The central component of MailerContrib is a script, `tools/mailnotify`, that generates and sends out the emails based on analysis of
1. users' subcriptions listed in the WebNotify topic in each web, and
2. changes within the respective webs.
Each web can optionally contain a topic called WebNotify.
-Users subscribe to email notifications using their [[WikiName]] or an alternative email address, and can specify the webs/topics they wish to track using one of these bullet list formats:
+Users subscribe to email notifications using their [[WikiName]] or an alternative email address, and can specify the webs/topics they wish to track, WWhole groups of users can also be subscribed for notification.
+
+The general format of a subscription is:
+
+_three spaces_ `*` _subscriber_ [ `:` _topics_ ]
+
+Where _subscriber_ can be a [[WikiName]], an E-mail address, or a group name. If _subscriber_ contains any characters that are not legal in an email address, then it must be enclosed in 'single' or "double" quotes.
+
+_topics_ is an optional space-separated list of topics:
-_three spaces_ \* [ _webname_ . ] _wikiName_ - _SMTP mail address_<br />_three spaces_ \* [ _webName_ . ] _wikiName_<br />_three spaces_ \* _SMTP mail address_<br />_three spaces_ \* _SMTP mail address_ : _topics_<br />_three spaces_ \* [ _webname_ . ] _wikiName_ : _topics_
+- ... **without** a _Web._ prefix
+- ...that exist in this web.
-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:
+Users may further customize the specific content they will receive using the following controls:
-- 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 ('+').
+- You can use `*` in a topic name, where it is treated as a [wildcard character](http://en.wikipedia.org/wiki/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, ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions.
+- 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.
For example: Subscribe Daisy to all changes to topics in this web.
* daisy.cutter@flowers.com
-Subscribe Daisy to all changes in all webs that start with `Web`.
+Subscribe Daisy to all changes to topics that start with `Web`.
- * daisy.cutter@flowers.com: Web*
+ * daisy.cutter@flowers.com : Web*
Subscribe Daisy to changes to topics starting with `Petal`, and their immediate children, WeedKillers and children to a depth of 3, and all topics that match start with `Pretty` and end with `Flowers` e.g. `PrettyPinkFlowers`
* GardenGroup: AllNewsLetters? (3)
* petunia@flowers.com: - ManureNewsLetter
-A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify that all match the same topic, they will only be notified about _changes_ that topic _once_ (though they will still receive individual mails for news topics).
-
-If a _TWiki group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
-
-**_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
-
-In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the `cron` job that runs the `mailnotify` script.
-
-%RED% **_Note_** `mailnotify` ignores permissions in webs. It is entirely possible for a user to get added to one of the subscription topics in a web, when they are not authorised to view the topics in that web. This could result in them having access to sensitive information, particularly with news mode. %ENDCOLOR%
-
-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.
-
-# <a name="TWiki/Contrib/_MailerContrib cod"></a> `TWiki/Contrib/MailerContrib` code library
-
-The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. The main interface is the `WebNotify` package described below.
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::WebNotify
-
-Object that represents the contents of a [[WebNotify]] topic in a TWiki web
-
-## <a name="ClassMethod new($web, $topic)"></a> [[ClassMethod]] new($web, $topic)
-
-Create a new object by parsing the content of the given topic in the given web. This is the normal way to load a [[WebNotify]] topic. If the topic does not exist, it will create an empty object.
-
-## <a name="ObjectMethod write_WebNotify()"></a> [[ObjectMethod]] writeWebNotify()
-
-Write the object to the [[WebNotify]] topic it was read from. If there is a problem writing the topic (e.g. it is locked), the method will return an error message. If everything is ok it will return undef.
-
-## <a name="ObjectMethod getSubscriber($name"></a> [[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
-
-Get a subscriber from the list of subscribers, and return a reference to the Subscriber object. If $noAdd is true, and the subscriber is not found, undef will be returned. Otherwise a new Subscriber object will be added if necessary.
-
-## <a name="ObjectMethod getSubscribers()"></a> [[ObjectMethod]] getSubscribers()
-
-Get a list of all subscriber names (unsorted)
-
-## <a name="ObjectMethod subscribe($name, $t"></a> [[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.
-
-Add a subscription, adding the subscriber if necessary.
-
-## <a name="ObjectMethod unsubscribe($name,"></a><a name="ObjectMethod unsubscribe($name, "></a> [[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)
-
-Add an unsubscription, adding the subscriber if necessary. An unsubscription is a specific request to ignore notifications for a topic for this particular subscriber.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -> string
-
-Return a string representation of this object, in [[WebNotify]] format.
-
-## <a name="ObjectMethod processChange($chan"></a> [[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
-
-Find all subscribers that are interested in the given change. Only the most recent change to each topic listed in the .changes file is retained. This method does _not_ change this object.
-
-## <a name="ObjectMethod processCompulsory($"></a> [[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
-
-## <a name="ObjectMethod isEmpty() - boolean"></a> [[ObjectMethod]] isEmpty() -> boolean
-
-Return true if there are no subscribers
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Subscriber
-
-Object that represents a subscriber to notification. A subscriber is a name (which may be a wikiName or an email address) and a list of subscriptions which describe the topis subscribed to, and unsubscriptions representing topics they are specifically not interested in. The subscriber name may also be a group, so it may expand to many email addresses.
-
-## <a name="ClassMethod new($name)"></a> [[ClassMethod]] new($name)
-
-- `$name` - Wikiname, with no web, or email address, of user targeted for notification
-
-Create a new user.
-
-## <a name="ObjectMethod get_EmailAddresses("></a> [[ObjectMethod]] getEmailAddresses() -> list
-
-Get a list of email addresses for the user(s) represented by this subscription
-
-## <a name="ObjectMethod subscribe($subs)"></a> [[ObjectMethod]] subscribe($subs)
-
-- `$subs` - Subscription object
-
-Add a new subscription to this subscriber object. The subscription will always be added, even if there is a wildcard overlap with an existing subscription.
-
-## <a name="ObjectMethod unsubscribe($subs)"></a> [[ObjectMethod]] unsubscribe($subs)
+Subscribe `IT:admins` (a non-TWiki group defined by an alternate user mapping) to all changes to Web\* topics.
-- `$subs` - Subscription object
+ * 'IT:admins' : Web*
-Add a new unsubscription to this subscriber object. The unsubscription will always be added, even if there is a wildcard overlap with an existing subscription or unsubscription.
-
-An unsubscription is a statement of the subscribers desire _not_ to be notified of changes to this topic.
-
-## <a name="ObjectMethod is_SubscribedTo($to"></a> [[ObjectMethod]] isSubscribedTo($topic) -> $subscription
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parents
-
-Check if we have a subscription to the given topic. Return the subscription that matches if we do, undef otherwise.
-
-## <a name="ObjectMethod is_UnsubscribedFrom"></a> [[ObjectMethod]] isUnsubscribedFrom($topic) -> $subscription
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parents
-
-Check if we have an unsubscription from the given topic. Return the subscription that matches if we do, undef otherwise.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -> string
-
-Return a string representation of this object, in WebNotify format.
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Subscription
-
-Object that represents a single subscription of a user to notification on a page. A subscription is expressed as a page spec (which may contain wildcards) and a depth of children of matching pages that the user is subscribed to.
-
-## <a name="ClassMethod new($pages, $childDe"></a> [[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.
-
-Create a new subscription.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -> string
-
-Return a string representation of this object, in WebNotify format.
-
-## <a name="ObjectMethod matches($topic, $db"></a> [[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.
-
-Check if we match this topic. Recurses up the parenthood tree seeing if this is a child of a parent that matches within the depth range.
-
-## <a name="ObjectMethod getMode() - $mode"></a> [[ObjectMethod]] getMode() -> $mode
-
-Return ! if this is a non-changes subscription and the topics should be mailed even if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
-
-----
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Change
-
-Object that represents a change to a topic.
-
-## <a name="ClassMethod new($web)"></a> [[ClassMethod]] new($web)
-
-- `$web` - Web name
-- `$topic` - Topic name
-- `$author` - String author of change
-- `$time` - String time of change
-- `$rev` - Revision identifier
-
-Construct a new change object.
-
-## <a name="ObjectMethod merge($change)"></a> [[ObjectMethod]] merge($change)
-
-- `$change` - Change record to merge
-
-Merge another change record with this one, so that the combined record is a reflection of both changes.
-
-## <a name="ObjectMethod expandHTML($html) -"></a> [[ObjectMethod]] expandHTML($html) -> string
-
-- `$html` - Template to expand keys within
-
-Expand an HTML template using the values in this change. The following keys are expanded: %TOPICNAME%, %AUTHOR%, %TIME%, %REVISION%, %TEXTHEAD%.
-
-Returns the expanded template.
-
-## <a name="ObjectMethod expandPlain() - str"></a> [[ObjectMethod]] expandPlain() -> string
+A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify that all match the same topic, they will only be notified about _changes_ that topic _once_ (though they will still receive individual mails for news topics).
-Generate a plaintext version of this change.
+If a _group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::UpData
+\_\_%X% Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for email addresses. A user identified by an email address will only be sent change notifications if the topic they are asubscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogther, using the `{MailerContrib}{EmailFilterIn} setting in =configure`.
-Object that lazy-scans topics to extract parent relationships.
+**_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
-## <a name="ClassMethod new($web)"></a> [[ClassMethod]] new($web)
+In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the `cron` job that runs the `mailnotify` script.
-- `$web` - Web we are building parent relationships for
+Note that when using the "news mode" `!` or `?` specifiers 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.
-Constructor for a web; initially empty, will lazy-load as topics are referenced.
+In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.
-## <a name="ObjectMethod getParent($topic) -"></a> [[ObjectMethod]] getParent($topic) -> string
+## <a name="TWiki/Contrib/_MailerContrib cod"></a> TWiki/Contrib/MailerContrib code library
-Get the name of the parent topic of the given topic
+The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. Developers should refer to the POD documentation for the WebNotify class as their starting point.
-# <a name="package TWiki::Contrib::Mailer"></a> package TWiki::Contrib::Mailer
+## <a name="Installation Instructions"></a> Installation Instructions
-Package of support for extended WebNotify notification, supporting per-topic notification and notification of changes to children.
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
-Also supported is a simple API that can be used to change the WebNotify topic from other code.
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
-## <a name="StaticMethod mailNotify($webs, $"></a> [[StaticMethod]] mailNotify($webs, $session, $verbose)
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
+ - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+ 1. Download one of the `.zip` or `.tgz` archives
+ 2. Unpack the archive in the root directory of your TWiki installation.
+ 3. Run the installer script ( `perl <module>_installer` )
+ 4. Run `configure` and enable the module, if it is a plugin.
+ 5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+ 1. Make sure that the file permissions allow the webserver user to access all files.
+ 2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+ 3. Manually edit LocalSite.cfg to set any configuration variables.
-- `$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
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre> * Set SYSTEMWEB = %TWIKIWEB%<br /> * Set USERSWEB = %MAINWEB%</pre></div>
-Main entry point.
+- 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`.
-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.
+**Additional settings**
-# <a name="Installation Instructions"></a> Installation Instructions
+- You can change the regular expression that matches email addresses in WebNotify using the `{MailerContrib}{EmailFilterIn} setting in =configure`. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
-You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+### <a name="Setting up your cron job(s)"></a> Setting up your cron job(s)
-Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+You need to set up a `cron` (or equivalent) job to run the `tools/mailnotify` perl script.
-- 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](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.
- 3. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
- 4. Manually edit LocalSite.cfg to set any configuration variables.
- 5. Run `configure` and enable the module, if it is a plugin.
- 6. 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.
-
-## <a name="Setting up your cron job(s)"></a> Setting up your cron job(s)
-
-You need to set up a `cron` (or equivalent) job to run `tools/mailnotify`.
-
-Usage: <code>perl -I <bin> mailnotify [-q] [-news] [ _web1 web2 ... webN_ ]</code> <bin> is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
+The script is used as follows: <code>perl -I _bin_ mailnotify [-q] [-news] [ _web1 web2 ... webN_ ]</code>
<table border="1" cellpadding="0" cellspacing="0">
<tr>
+ <td><em>bin</em></td>
+ <td> path to the TWiki bin directory, so that the script can find the rest of TWiki. </td>
+ </tr>
+ <tr>
<td><code>-q</code></td>
<td> Don't print progress information </td>
</tr>
</tr>
<tr>
<td><code><i>web1 web2 ... webN</i></code></td>
- <td> List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported. </td>
+ <td> List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported. </td>
</tr>
</table>
0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Private
-will generate change notifications for the `Public` and `Private` webs every night at midnight.
+will generate change notifications for the `Public` and `Private` webs every night at midnight. (Google for `crontab` for more information on what all the `0 0 * * *` fields mean)
+
+ 0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandbox
+
+will generate change notifications for all webs, except the `Sandbox` web.
0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news
will generate newsletters from **all** webs every week on midnight Saturday.
-# <a name="Developer Notes"></a> Developer Notes
+## <a name="Developer Notes"></a> Developer Notes
The changes mails sent to users are based on a TWiki template called `mailnotify`. This template must contain the following definitions.
Newsletters are sent after formatting using the standard `view` template, using whatever skin is selected in the topic being mailed.
-## <a name="Contrib Info"></a> Contrib Info
+### <a name="Contrib Info"></a> Contrib Info
+
+Another great TWiki extension from the [![](http://www.dementia.org/twiki//view/wikiring.png) **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
+Many thanks to the following sponsors for supporting this work:
+
+- [Wind River](http://www.windriver.com)
+- [WikiGardens](http://wikigardens.com)
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td> GPL </td>
</tr>
<tr>
+ <td align="right"> Version: </td>
+ <td> 16078 (22 Jan 2008) </td>
+ </tr>
+ <tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 2 Nov 2007 </td>
+ <td> Bugs:Item4818: added quotes to support non-alphabetic and other wierd group names Bugs:Item4887: corrected minor rendering error Bugs:Item4917: removed dependence on symbolic web names </td>
+ </tr>
+ <tr>
+ <td align="right"> 9 Sep 2007 </td>
+ <td> Bugs:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users. </td>
+ </tr>
+ <tr>
+ <td align="right"> 6 Sep 2007 </td>
+ <td> Bugs:Item4488 doc tweaks </td>
+ </tr>
+ <tr>
+ <td align="right"> 14550 </td>
+ <td> Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history </td>
+ </tr>
+ <tr>
+ <td align="right"> 22 Jun 2007 </td>
+ <td> Bugs:Item4284 - added access control checks and email filter </td>
+ </tr>
+ <tr>
+ <td align="right"> 21 May 2007 </td>
+ <td> Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris) </td>
+ </tr>
+ <tr>
+ <td align="right"> 13623 </td>
+ <td> Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down. </td>
+ </tr>
+ <tr>
<td align="right"> 12496 </td>
<td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item3415" rel="nofollow">Item3415</a> mailnotify did not send notifications to intranet users because of wrong call to findUser. </td>
</tr>