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;
This says that information about page changes should be periodically emailed to email@example.com. The Site.Notify List page can contain multiple "notify=" lines to cause notifications to be sent to multiple addresses.
A number of options exist for limiting the pages that result in a notification. The
# send notifications about the Main group to firstname.lastname@example.org email@example.com group=Main # notify firstname.lastname@example.org of any changes to the home page email@example.com name=Main.Home Page # notify firstname.lastname@example.org of changes to pages except in Main email@example.com group=-Main
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.Notify List will send firstname.lastname@example.org an email containing changes to any of the pages listed in the Profiles.Alice trail:
# notify Alice of changes to pages listed in Profiles.Alice email@example.com trail=Profiles.Alice
Note that once this entry has been added to Site.Notify List, Alice can easily change her watchlist by editing the Profiles.Alice page and doesn't need to edit the Site.Notify List page. In particular, this means that an administrator can restrict editing of Site.Notify List, yet allow individuals to maintain custom watchlists in other pages.
This is probably a good place to point out that edit access to Site.Notify List should be controlled, otherwise malicious persons can use the notification capability to flood others' electronic mailboxes. By default, Site.Notify is blocked against edits except by the admin (as is the case for most pages in the Site group). It may also be useful to place a read password on the Site.Notify List page, to restrict the availability of email addresses from spam harvesters.
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 (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
# enable notifications $EnableNotify = 1; $NotifySquelch = 86400; # wait at least one day between notifications
In addition, individual addresses can specify a custom squelch parameter in the Site.Notify List page:
# Alice receives at most one email per day firstname.lastname@example.org squelch=86400 # Bob can get notifications hourly email@example.com trail=Profiles.Bob squelch=3600 # Charles uses the site default squelch firstname.lastname@example.org
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:
# enable 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 Pm Wiki 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. (Active sites will
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.
$EnableNotify = 1; # enable notify $EnableNotify = 0; # disable notify
$NotifyFrom = 'email@example.com'; $NotifyFrom = 'Wiki server <firstname.lastname@example.org>';
$NotifyDelay = 300; # send mail 5+ min after first post
$NotifySquelch = 43200; # wait 12+ hours between mailings
# default $NotifyItemFmt = ' * $FullName . . . $PostTime by $Author'; # include the page's URL in the message $NotifyItemFmt = " * \$FullName . . . \$PostTime by \$Author\n \$PageUrl";
$NotifyTimeFmt = 'm-H:%M'; # 2004-03-20 17:44
# send notifications to email@example.com $NotifyList = 'firstname.lastname@example.org'