1 version=pmwiki-2.3.5 ordered=1 urlencoded=1
4 csum=hlt php, pm hlt, http+s (+984)
8 targets=PmWiki.LocalCustomizations,PmWiki.Notify,SiteAdmin.NotifyList,PmWiki.PageLists,PmWiki.WikiTrails,PmWiki.PageTextVariables,PmWiki.BasicVariables,PmWiki.UTF-8,PITS.01159
9 text=(:Summary:How to receive email messages whenever pages are changed on the whole wiki site, individual groups or selected watchlists of pages:)%0a(:Audience: administrators (basic) :)%0aThe ''@@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).%0a%0aThis 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.%0a%0aIn order for notifications to work, the @@notify.php@@ script must be enabled in the site's [[local customization(s)]]. Usually this is as simple as placing the following in ''@@local/config.php@@'':%0a%0a->%25hlt php%25@@$EnableNotify = 1;@@%0a%0a!! Notification configuration%0aOnce enabled, the notification system gets its configuration from the [[SiteAdmin.NotifyList]] wiki page. The @@SiteAdmin.NotifyList@@ page contains entries of the form:%0a%0a->%25hlt php%25@@notify=alice@example.com@@%0a%0aThis says that information about page changes should be periodically emailed to ''@@alice@example.com@@''. The @@SiteAdmin.NotifyList@@ 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 %25pmhlt%25[@(:if false:)@] conditional section on the page.%0a%0aNOTE: Do not put any spaces around the equal sign! Notifications will fail silently if you have... This is a really easy mistake to make because all of the other assignments have spaces around the equal sign.%0a %0a->%25green%25notify=fred@example.com%25%25 rather than %25red%25notify = fred@example.com%25%25%0a%0a!! Notification options%0aThe basic syntax is %0a->%25hlt php%25@@notify=''email@address'' \%0a [[#notifyname|name]]=''abc'' \%0a [[#notifygroup|group]]=''def'' \%0a [[#notifytrail|trail]]=''ghi'' \%0a [[#notifysquelch|squelch]]=''123'' \%0a [[#notifydelay|delay]]=''123'' \%0a [[#tz|tz]]=''123'' \%0a @@%0a%0aA 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:%0a%0a[[#notifygroup]]%0a->%25hlt php%25@@# send notifications about the Main group to alice@example.com@@%0a->%25hlt php%25@@notify=alice@example.com '''group'''=Main@@%0a%0a[[#notifyname]]%0a->%25hlt php%25@@# notify bob@example.com of any changes to the home page@@%0a->%25hlt php%25@@notify=bob@example.com '''name'''=Main.HomePage@@%0a%0a->%25hlt php%25@@# notify charles@example.com of changes to pages except in Main@@%0a->%25hlt php%25@@notify=charles@example.com '''group'''=-Main@@%0a%0a(Note: The options are similar to [[PmWiki/PageLists | the PageList syntax]].)%0a%0a[[#notifytrail]]%0aFor maintaining arbitrary lists of pages, i.e., "watchlists", it's generally easier to build a [[trail -> WikiTrails]] of pages to be watched. The following entry in @@SiteAdmin.NotifyList@@ will send @@alice@example.com@@ an email containing changes to any of the pages listed in the @@Profiles.Alice@@ trail:%0a%0a->%25hlt php%25@@# notify Alice of changes to pages listed in Profiles.Alice@@%0a->%25hlt php%25@@notify=alice@example.com '''trail'''=Profiles.Alice@@%0a%0aNote that once this entry has been added to @@SiteAdmin.NotifyList@@, Alice can easily change her watchlist by editing the @@Profiles.Alice@@ page, and doesn't need to edit the @@SiteAdmin.NotifyList@@ page. In particular, this means that an administrator can restrict editing of @@SiteAdmin.NotifyList@@, yet allow individuals to maintain custom watchlists in other pages. %0a%0aLimitations of this feature:%0a* only manually-added links on a trail will be acknowledged by the Notify List (no "group=" or other pagelist syntax, nor any "@@Group.RecentChanges@@" links, will generate notifications)%0a* using an %25pmhlt%25[@(:include:)@] directive on the page @@SiteAdmin.NotifyList@@ is not an operational work-around.%0a* [[PageTextVariables]] are not resolved - you can't get the notification mail address from the profile page.%0a%0aThis is probably a good place to point out that edit access to @@SiteAdmin.NotifyList@@ should be controlled, otherwise malicious persons can use the notification capability to flood others' electronic mailboxes. By default, @@SiteAdmin.NotifyList@@ is blocked against reading or edits except by the admin (as is the case for most pages in the @@SiteAdmin@@ group).%0a%0a!! Adding notification entries via local customizations%0a%0aNotification entries can also be added via the @@$NotifyList@@ array in ''@@local/config.php@@''. Simply add a line like the following:%0a->%25hlt php%25@@$EnableNotify = 1;@@%0a->%25hlt php%25@@$NotifyList[] = 'notify=alice@example.com group=Main';@@%0a->%25hlt php%25@@$NotifyList[] = 'notify=bob@example.com name=Main.HomePage';@@%0a%0a[[#controlling_notification_frequency]]%0a[[#notifysquelch]]%0a!! Controlling notification frequency%0a%0aTo 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.%0a%0aThe site administrator can change the default squelch interval via the @@$NotifySquelch@@ parameter %0a%0a->%25hlt php%25@@# enable notifications@@%0a->%25hlt php%25@@$EnableNotify = 1;@@%0a->%25hlt php%25@@$NotifySquelch = 86400; # wait at least one day (in seconds) between notifications@@%0a%0aIn addition, individual addresses can specify a custom squelch parameter in the @@SiteAdmin.NotifyList@@ page:%0a%0a->%25hlt php%25@@# Alice receives at most one email per day@@%0a->%25hlt php%25@@notify=alice@example.com '''squelch'''=86400@@%0a%0a->%25hlt php%25@@# Bob can get notifications hourly@@%0a->%25hlt php%25@@notify=bob@example.com trail=Profiles.Bob '''squelch'''=3600@@%0a%0a->%25hlt php%25@@# Charles uses the site default squelch@@%0a->%25hlt php%25@@notify=charles@example.com @@%0a%0a[[#notifydelay]]%0a!! Controlling notification delay%0aBecause 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:%0a%0a->%25hlt php%25@@# enable notifications@@%0a->%25hlt php%25@@$EnableNotify = 1;@@%0a->%25hlt php%25@@$NotifySquelch = 86400; # wait at least one day between notifications@@%0a->%25hlt php%25@@$NotifyDelay = 300; # wait five minutes after initial post@@%0a%0aNote 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. [[Wikipedia:Cron | cron job]]).%0a%0aCustom delay parameters cannot be specified for individual addresses in the [[SiteAdmin.NotifyList]] page:%0a%0a->%25hlt php%25@@# the delay= parameter will be ignored@@%0a->%25hlt php%25@@notify=edgar@example.com trail=Profiles.Edgar '''delay'''=600@@%0a%0a[[#tz]]%0a!! Time zone%0aSince PmWiki 2.3.0, individual users can configure the date and time stamps to show in their own timezone, for example:%0a%0a->%25hlt php%25@@notify=edgar@example.com [other arguments] '''tz'''=Europe/Paris@@%0a%0aFind your timezone in this [[https://www.php.net/manual/en/timezones.php|list of supported timezones]].%0a%0a!! Note for Windows installations%0a%0aSites running PHP under Windows may not have PHP's [[https://www.php.net/manual/en/function.mail.php | mail]] function configured correctly. Such sites may need to add a line like%0a%0a->%25hlt php%25@@ini_set('SMTP','smtp.server.com');@@%0a%0ato ''@@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:%0a%0a->%25hlt php%25@@ini_set('sendmail_from','noreply@foo.com');@@%0a%0a%0a!![[#variables]] Notify Variables%0a%0a:$EnableNotify:Tells ''@@stdconfig.php@@'' to enable the notify script.%0a: :%25hlt php%25@@$EnableNotify = 1; # enable notify@@%0a: :%25hlt php%25@@$EnableNotify = 0; # disable notify@@%0a%0a:$MailFunction: The function to call when sending a message, default the built-in PHP function [[https://www.php.net/manual/en/function.mail.php|mail]]. If you have some custom e-mailing solution or library, place here the function to be called with the same arguments as %25hlt php%25@@mail($to, $subject, $message, $additional_headers)@@.%0a%0a:$NotifyFrom:Return email address to be used in the sent email.%0a: :%25hlt php%25@@$NotifyFrom = 'wiki@example.com';@@%0a: :%25hlt php%25@@$NotifyFrom = 'Wiki server %3cwiki@example.com>';@@%0a%0a:$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.%0a: :%25hlt php%25@@$NotifyDelay = 300; # send mail 5+ min after first post@@%0a%0a:$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 @@SiteAdmin.NotifyList@@ page.%0a: :%25hlt php%25@@$NotifySquelch = 43200; # wait 12+ hours between mailings@@%0a%0a:$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).%0a: :%25hlt php%25@@# default@@%0a: :%25hlt php%25@@$NotifyItemFmt = ' * $FullName . . . $PostTime by $Author';@@%0a%0a: :%25hlt php%25@@# include the page's URL in the message@@%0a: :%25hlt php%25@@$NotifyItemFmt = " * \$FullName . . . \$PostTime by \$Author\n \$PageUrl";@@%0a%0a: :%25hlt php%25@@# include the change summary and link to the page's history in the message@@%0a: :%25hlt php%25@@$NotifyItemFmt = " * {\$FullName} . . . \$PostTime by {\$Author}\n Summary: {\$LastModifiedSummary}\n {\$PageUrl}?action=diff";@@%0a%0a%0a:$NotifyTimeFmt:The format for dates/times in @@$PostTime@@ above. Defaults to the value of @@$TimeFmt@@.%0a: :%25hlt php%25@@$NotifyTimeFmt = [='%25Y-%25m-%25d %25H:%25M'=]; # 2004-03-20 17:44@@%0a%0a:$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@@. %0a: :%25hlt php%25@@$NotifyBodyFmt = "Changed items:\n\n" . '$NotifyItems' . "\n\n Best regards...";@@%0a%0a:$NotifySubjectFmt:The subject line of the mail to be sent.%0a%0a:$NotifyHeaders:String of extra mail headers to be passed to the %25hlt php%25@@mail()@@ function.%0a%0a:$NotifyParameters:String of additional parameters to be passed to PHP's %25hlt php%25@@mail()@@ function [[https://www.php.net/manual/en/function.mail.php|#]].%0a%0a:$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.%0a%0a:$NotifyListPageFmt:The name of the page containing [@notify=@] lines for use by ''@@notify.php@@''. Defaults to [@$SiteAdminGroup.NotifyList@].%0a%0a:$NotifyList:An array of [@notify=@] specifications that can be specified from a local customization file (used in addition to entries in SiteAdmin.NotifyList).%0a: :%25hlt php%25@@# send notifications to alice@example.com@@%0a: :%25hlt php%25@@$NotifyList[] = 'notify=alice@example.com';@@%0a%0a:$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).%0a: :%25hlt php%25@@$EnableNotifySubjectEncode = 1; # encode subject@@%0a: :%25hlt php%25@@$EnableNotifySubjectEncode = 0; # use subject as is (default)@@%0a: : To fix encodings with the message body, add to @@config.php@@ the following line (after XLPage and/or [[UTF-8]]):\\%0a %25hlt php%25@@$NotifyHeaders = "Content-type: text/plain; charset=$Charset";@@%0a%0a!! Notification only for major edits%0a%0aIt is possible to send notifications only in case of major edits. In your @@config.php@@, replace "@@$EnableNotify=1;@@" with the following: %0a%0a%25hlt php%25@@if ( @$_POST['diffclass'] != 'minor' ) $EnableNotify=1;@@%0a%0aThis 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:%0a%0a%25hlt php%25@@if ( @$_POST['diffclass'] == 'minor' ) $EnableNotify=1;@@%0a%0ainstead.%0a%0a!! Disabling notifications for downloads%0a%0aIf 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%0a%0a%25hlt php%25@@if ( $action != 'download' ) $EnableNotify=1;@@%0a%0aThat way, only page views (and not images within the page) will generate notifications. See PITS:01159 for more information.%0a
