Notify
← Blocklist | Variables | Basic Variables →
The notify.php script allows a site administrator to configure PmWiki to send email messages whenever pages are changed on the wiki site. Notifications can be configured so that multiple page changes over a short period of time are combined into a single email message (to avoid flooding mailboxes).
This feature is useful for sites and pages that have infrequent updates, as it eliminates the need to frequently check RecentChanges pages just to see if anything has changed.
In order for notifications to work, the notify.php script must be enabled in the site’s local customization. Usually this is as simple as placing the following in local/config.php:
$EnableNotify
= 1;
Notification configuration
Once enabled, the notification system gets its configuration from the SiteAdmin.NotifyList? wiki page. The Site Admin.Notify List? page contains entries of the form:
This says that information about page changes should be periodically emailed to alice@example.com. The Site Admin.Notify List? page can contain multiple “notify=“ lines to cause notifications to be sent to multiple addresses; the “notify=“ lines can be concealed by placing them inside of an (:if false:)
conditional section on the page.
Notification options
The basic syntax is
A number of options exist for limiting the pages that result in a notification. The group=
and name=
parameters can be used to restrict notifications to specific pages or groups:
(Note: The options are similar to the PageList syntax.)
For maintaining arbitrary lists of pages, i.e., “watchlists”, it’s generally easier to build a trail of pages to be watched. The following entry in Site Admin.Notify List? will send alice@example.com an email containing changes to any of the pages listed in the Profiles.Alice trail:
Note that once this entry has been added to Site Admin.Notify List?, Alice can easily change her watchlist by editing the Profiles.Alice page, and doesn’t need to edit the Site Admin.Notify List? page. In particular, this means that an administrator can restrict editing of Site Admin.Notify List?, yet allow individuals to maintain custom watchlists in other pages.
Limitations of this feature:
- only manually-added links on a trail will be acknowledged by the Notify List (no “group=“ or other pagelist syntax, nor any “Group.Recent Changes?” links, will generate notifications)
- using an
(:include:)
directive on the page Site Admin.Notify List? is not an operational work-around. - PageTextVariables are not resolved - you can’t get the notification mail address from the profile page.
This is probably a good place to point out that edit access to Site Admin.Notify List? should be controlled, otherwise malicious persons can use the notification capability to flood others’ electronic mailboxes. By default, Site Admin.Notify List? is blocked against reading or edits except by the admin (as is the case for most pages in the Site Admin group).
Adding notification entries via local customizations
Notification entries can also be added via the $NotifyList
array in local/config.php. Simply add a line like the following:
$EnableNotify
= 1;
$NotifyList
[] = ‘notify=alice@example.com group=Main’;
$NotifyList
[] = ‘notify=bob@example.com name=Main.Home Page’;
Controlling notification frequency
To prevent flooding of recipients’ mailboxes, the notify script uses a “squelch” value as the minimum amount of time that must elapse between messages sent to any given email address. The default squelch setting is 10800 seconds (three hours), which means that once a recipient address is sent a notification message, it will not receive another for at least three hours. Any edits that occur during the squelch interval are queued for the next notification message.
The site administrator can change the default squelch interval via the $NotifySquelch
parameter
$EnableNotify
= 1;
$NotifySquelch
= 86400; # wait at least one day (in seconds) between notifications
In addition, individual addresses can specify a custom squelch parameter in the Site Admin.Notify List? page:
Controlling notification delay
Because a page will often receive several edits in rapid succession (e.g., a long post followed by several minor edits), a site administrator can also set a $NotifyDelay
value that specifies how long to wait after an initial post before sending notifications:
$EnableNotify
= 1;
$NotifySquelch
= 86400; # wait at least one day between notifications
$NotifyDelay
= 300; # wait five minutes after initial post
Note that the squelch and delay values are minimums; notifications are sent on the first execution of PmWiki after the delay period has expired. For inactive sites, this could be much longer than the specified delay periods. This isn’t really considered an issue since timely notifications are less important on relatively inactive sites. However, changes within the squelch time after the last notification will remain unnoticed if the wiki is not even visited for a long period after. If this matters it might be necessary to make the server call pmwiki.php regularly (e.g. cron job).
Custom delay parameters cannot be specified for individual addresses in the SiteAdmin.NotifyList? page:
delay=
parameter will be ignored
Note for Windows installations
Sites running PHP under Windows may not have PHP’s mail function configured correctly. Such sites may need to add a line like
to config.php, where smtp.server.com is the name of your host’s preferred outgoing mail server. You may also need to set the sendmail_from value if that is not configured:
Notify Variables
- %apply=item id=Enable Notify?%
$EnableNotify
- Tells stdconfig.php to enable the notify script.
$EnableNotify
= 1; # enable notify
$EnableNotify
= 0; # disable notify
- %apply=item id=Mail Function?%
$MailFunction
- The function to call when sending a message, default the built-in PHP function mail. If you have some custom e-mailing solution or library, place here the function to be called with the same arguments as mail($to, $subject, $message, $additional_headers).
- %apply=item id=Notify From?%
$NotifyFrom
- Return email address to be used in the sent email.
$NotifyFrom
= ‘wiki@example.com’;
$NotifyFrom
= ‘Wiki server <wiki@example.com>’;
- %apply=item id=Notify Delay?%
$NotifyDelay
- The length of time (seconds) to wait before sending mail after the first post. Defaults to zero - posts are sent as soon as any squelch period has expired.
$NotifyDelay
= 300; # send mail 5+ min after first post
- %apply=item id=Notify Squelch?%
$NotifySquelch
- The default minimum time (seconds) that must elapse between sending mail messages. Useful when
$NotifyDelay
is set to a small value to keep the number of mail notification messages down. Defaults to 10800 (three hours). Individual recipients can override this value in the Site Admin.Notify List? page.
$NotifySquelch
= 43200; # wait 12+ hours between mailings
- %apply=item id=Notify Item Fmt?%
$NotifyItemFmt
- The text to be sent for each changed item in the post. The string “$PostTime” is substituted with the time of the post (controlled by
$NotifyTimeFmt
below).
$NotifyItemFmt
= ‘ * $FullName . . . $PostTime by $Author
’;
$Author
\n \$PageUrl”;
$Author
.gif' border='0' alt='\$Author
smiley' title='\$Author
smiley' class='smiley' />
- %apply=item id=Notify Time Fmt?%
$NotifyTimeFmt
- The format for dates/times in $PostTime above. Defaults to the value of
$TimeFmt
.
$NotifyTimeFmt
= '%Y-%m-%d %H:%M'; # 2004–03–20 17:44
- %apply=item id=Notify Body Fmt?%
$NotifyBodyFmt
- The body of the message to be sent. The string “$NotifyItems” is replaced with the list of posts (as formatted by
$NotifyItemFmt
above). Use single quotation marks ‘ to prevent substring “$NotifyItems” from being untimely evaluated as variable in config.php.
$NotifyBodyFmt
= “Changed items:\n\n” . ‘$NotifyItems’ . “\n\n Best regards…”;
- %apply=item id=Notify Subject Fmt?%
$NotifySubjectFmt
- The subject line of the mail to be sent.
- %apply=item id=Notify Headers?%
$NotifyHeaders
- String of extra mail headers to be passed to the mail() function.
- %apply=item id=Notify Parameters?%
$NotifyParameters
- String of additional parameters to be passed to PHP’s mail() function [1].
- %apply=item id=Notify File?%
$NotifyFile
- The scratch file where Notify keeps track of recent posting information. Defaults to
"$WorkDir/.notifylist"
. Note that this file must generally be writable by the webserver process. - %apply=item id=Notify List Page Fmt?%
$NotifyListPageFmt
- The name of the page containing
notify=
lines for use by notify.php. Defaults to$SiteAdminGroup.NotifyList
. - %apply=item id=Notify List?%
$NotifyList
- An array of
notify=
specifications that can be specified from a local customization file (used in addition to entries in Site Admin.Notify List?).
$NotifyList
[] = ‘notify=alice@example.com’;
- %apply=item id=Enable Notify Subject Encode?%
$EnableNotifySubjectEncode
- Apply a standard (base64) encoding for the e-mail subject. Notify e-mails from international wikis may otherwise have unreadable subjects (added for version 2.2.2).
$EnableNotifySubjectEncode
= 1; # encode subject
$EnableNotifySubjectEncode
= 0; # use subject as is (default)
$NotifyHeaders
= “Content-type: text/plain; charset=$Charset”;
Notification only for major edits
It is possible to send notifications only in case of major edits. In your config.php, replace “$EnableNotify
=1;” with the following:
if ( @$_POST[‘diffclass’] != ‘minor’ ) $EnableNotify
=1;
This way, only ‘major’ edits send notify messages (when the author doesn’t select the checkbox for minor edit). If you want minor edits and not major edits to send the message then you would use:
if ( @$_POST[‘diffclass’] == ‘minor’ ) $EnableNotify
=1;
instead.
Disabling notifications for downloads
If you use “$EnableDirectDownloads=0;” (eg. for privacy on a password-protected wiki) then attached images may generate duplicate notification messages. To prevent that disable notifications for downloads via
if ( $action != ‘download’ ) $EnableNotify
=1;
That way, only page views (and not images within the page) will generate notifications. See PITS:01159 for more information.
← Blocklist | Variables | Basic Variables →
This page may have a more recent version on pmwiki.org: PmWiki:Notify, and a talk page: PmWiki:Notify-Talk.