• View
• Edit
• History
• Attach
• Print
• Backlinks

FoxNotify

Questions answered by this recipe

• How can I add email notification to Fox when pocsting comments, topics etc.?
• How can I enhance forum participation by sending out notifications to different groups of members according to what their interests are?
• How can I create a simple form-based e-bulletin system?
• How can I add a form which lets members subscribe to email notifications, according to their interests?

Description

• FoxNotify adds email notification and mailing capability to Fox forms.
• When a post is made, Fox will trigger FoxNotify to send notification emails to a list of recipients.
• A field foxnotify determines which Notify List page or pages from the FoxNotifyLists group are used.
• Using (:foxmail ...:) no posting needs to be made, the markup will action the mailing directly. Email template and Email list target can be specified directly.
• The format of the email notification can be set with a template= or format= parameter for each individual email address.
• Templates for email formats can be created on a wiki page FoxNotifyTemplates.
• Email body formats can include the topic name and the content of a post (a forum post for instance), as well as any other input field values.
• A GeneralNotifyList can be used for general notifications on page changes anywhere within the wiki, the same as with PmWiki.Notify, on which development of FoxNotify is based.
• Messages can be HTML formatted by setting $EnableFoxNotifyHTMLEmail = true; Wiki markup in email template and input boxes will be rendered as HTML for the email message body.

Installation

Install foxnotify.php in the usual way: copy to Cookbook folder and set in local config.php:

Set in config.php before the include a line:

All email lists are on pages within a special group, by default FoxNotifyLists.
The pages in this group will need special consideration and protection from public editing.

Adding foxnotify to a Fox form

Add the name of a notification list page (in the FoxNotifyLists group) as value to a form field with name =foxnotify. This could also be an array of list page names, to mail to several lists at once.

Example 1:

To send notifications automatically to all recipients on ListA, add to your fox form:

(:input hidden foxnotify ListA:)

Example 2:

To let the author/poster choose from a number of lists, using a drop down box, add to your fox form:

(:input select foxnotify[] "" "none" size=1 multiple:)
(:input select foxnotify[] ListA "List A":)
(:input select foxnotify[] ListB "List B":)
(:input select foxnotify[] ListC "List C":)

Example 3:

To let the author/poster choose from a number of lists, using check boxes, add to your fox form:

(:input checkbox foxnotify[] ListA "List A":)
(:input checkbox foxnotify[] ListB "List B":)
(:input checkbox foxnotify[] ListC "List C":)

Adding (:foxmail ....:) or foxaction=mail to a Fox form

The target page (as a NotifyList page containing lines with recipient's email addresses) needs to have page permission set for 'mail'. No content need to be posted to any page. This is the difference to using foxnotify as above. But content could be posted as another foxaction (see Fox multiple targets).

(:foxmail template=EMailTemplate target=EMailList :)

for sending email message to small group of recipients on EMailList.

(:fox formname foxaction=mail template=EMailTemplate target=EMailList :)

alternative syntax.

Mail Form Example:

Send message via a contact form (with foxcheck validation):

%red%(:foxmessage eform:)
!!You can send a message to us using the form below:
''Please fill in all form fields!''
(:fox eform :)
(:foxmail template=FoxNotifyLists.MailFormTemplate target=FoxNotifyLists.EmailList foxsuccess='E-mail sent successfully!' :)
(:foxcheck name msg='Please add your name!':)
Your name:
(:input text name size=30:) %red%(:foxmessage eform name:)
(:foxcheck email msg='Please add your e-mai addresse!':)
Your e-mail address:
(:input text email size=30:) %red%(:foxmessage eform email:)
(:foxcheck subject msg='Please add subject!':)
Subject:
(:input text subject size=30:) %red%(:foxmessage eform subject:)
(:foxcheck text msg='Please add message!':)
Message: %red%(:foxmessages eform text:)
(:input textarea text cols=70 rows=8:)
(:input submit post 'Send E-mail':)
(:foxend eform:)

MailFormTemplate needs to be like FoxNotifyTemplates. EmailList needs to be a NotifyList (even if it contains just one address).

Mail Form Template Example:

(:linebreaks:)
!!Email subject format
[[#subject]]
$WikiTitle Contact Message
[[#subjectend]]

!!Email body heading format
[[#heading]]
Newest enquiry on $WikiTitle ContactUs page:
[[#headingend]]

!!Email item formats
[[#default]]
Sent: $PostTime 
Name: {$$name}   
E-Mail: {$$email}
Subject: {$$subject}

{$$text}

============================
Sent by $WikiTitle Server to $FoxRecipient
[[#defaultend]]

Parameters for NotifyList pages

• notify=email-address - essential
• recipient=Recipient Name - this string will substitute the general variable $MailRecipient when this is used in the 'heading' or 'default' sections of the MailFormTemplate.
• salutation=Salutation string - this string will substitute the general variable $MailSalutation when this is used in the 'heading' or 'default' sections of the MailFormTemplate.
• format=#default (or no format= parameter) for one line page link per item.
• format=#topic for page link plus topic name (from form field topic).
• format=#comment for page link, topic name and full content of post (from form field comment or text).

The format= (or alternatively template=) parameter needs to be defined on a FoxNotifyLists.FoxNotifyTemplates page (see example below).

• squelch=number - minimum number seconds delay in sending out email. See PmWiki.Notify.
• group=groupname - notifications for changes in group groupname only. See PmWiki.Notify.
• name=pagename - notifications for changes in page pagename only. See PmWiki.Notify.
• trail=trailpage - notifications for changes on pages specified as list on trailpage. See PmWiki.Notify.

Automatic notification of page changes

FoxNotifyLists.GeneralNotifyList can be used for notifying a list of recipients in a general way: Recipients will be notified of page changes anywhere on the wiki. Or page pattern parameters can be added (group=groupname, name=pagename, trail=trailpagename) same as for PmWiki.Notify. The GeneralNotifyList will always be used for notifications, whereas other lists in group FoxNotifyLists will need to be added within a foxnotify field in a fox input form. The GeneralNotifyList acts the same as the Site.NotifyList for PmWiki.Notify, thus can be potentially a substitute for using $EnableNotify and the notify.php script.

Optional settings for config.php

Display recipient name in To: field

Set in config.php

If a name is given in the recipient='....' parameter of the FoxNotifyList, this will add it in the To: field of the email client. Default is 0, just the email address is used.

entry in list: notify=name@example.com recipient='Some Name'

Adding recipients to a general notify list

You can add recipients from config.php by adding notify=email-address lines to the $FoxNotifyList array. for instance:

$FoxNotifyParameters

By default this string variable is empty. You can set it to add additional headers to the PHP mail() function. For example you can set a return path address with

    $FoxNotifyParameters = "-fbouncedmailmanager@example.com"; #set bouncedmailmanager@example.com as return path. 

Note the "-f" parameter switch before the email address! Substitute email address for the one you want to use.

HTML formatted messages

Set in config.php

and use appropriate wiki markup in the email template (But NOT the #subject section). Wiki markup entered in input boxes (for instance in a mail form, or a text box to generate a newsletter message) will also be rendered as HTML in the email message. If you want to have images in the text, use a full urls to the image location, not Attach:image.jpg. Otherwise the recipients email client will not find the image. But wiki links like [[Main.HomePage]] etc. are rendered as full urls and so no problem.

Using FoxNotifyTemplates

A page called FoxNotifyTemplates in the FoxNotifyLists group can be created to provide templates for the email formatting.

FoxNotifyTemplates Example:

!!Email subject format
[[#subject]]
$WikiTitle recent notify posts
[[#subjectend]]

!!Email body heading format
[[#heading]]
$MailSalutation $MailRecipient
Latest $WikiTitle post:
[[#headingend]]

!!Email item formats
!!!#default
[[#default]]
$ScriptUrl/$FullName . . . $PostTime by $LastModifiedBy
[[#defaultend]]

!!!#topic
[[#topic]]
$ScriptUrl/$FullName
Author: $LastModifiedBy   posted on $PostTime 
Topic: {$$topic}
[[#topicend]]

!!!#comment
[[#comment]]
$ScriptUrl/$FullName
Author: $LastModifiedBy   posted on $PostTime 
Topic: {$$topic}
=========================
{$$comment}
{$$text}
=========================
[[#commentend]]

• The #subject section will be used to create each email's subject line.
• The #heading section will be used to create each email's body heading (top of body, before the notify items).
• $MailRecipient will be replaced by the value from the recipient= parameter from each notify list line, or a default will be used.
• $MailSalutation will be replaced by the value from the salutation= parameter from each notify list line, or a default will be used.
• An item format section will be used for each item, according to the template= or format= parameter of the notify list line. The example defines options for these parameters: #basic, #topic and #comment.

The email body formats #topic and #comment show the use of replacement variables {$$varname}, which will be replaced in the email output with the value of the input form field of that name (similar to Fox form templates). Using other replacement variables any input form value can be incorporated in the email output, as well as other PmWiki variables, in the example $ScriptUrl/$FullName (page link), $LastModifiedBy (author), $PostTime (time stamp of posting).

If HTML formatting of messages is enabled, you can use Wiki markup in your email templates for formatting.

Using SMTP server instead of PHP mail()function

Install SMTPMail and set in config.php

   $MailFunction = "MailSMTP";

Debug

For test runs without mailing set in config.php

which will echo/display results of a mail form submission at the bottom of the screen, but without any emails are sent.

List of customisation variables for config.php

Several variables set defaults for this script, you can set different values in config.php before including the recipe script.

• $FoxNotifyDelay - number of seconds to wait before sending mail after the first post.
• $FoxNotifySquelch - minimum number of seconds between sending email messages to each address. Individual "notify=" lines in Site.NotifyList can override this value via a custom "squelch=" parameter.
• $FoxNotifyFile - scratchpad file used to keep track of pending emails.
• $FoxNotifyListsGroup - name of the group holding FoxNotifyList pages.
• $FoxGeneralNotifyList - name of general notify list page.
• $FoxNotifySubjectFmt - default subject line for sent messages.
• $FoxNotifyFrom - From: line for sent messages.
• $MailRecipient - string in template or body which gets replaced with recipient's name, as supplied by a recipient= parameter from the FoxNotifyLists lines.
• $MailSalutation - string in template or body which gets replaced with salutation, as supplied by a salutation= parameter from the FoxNotifyLists lines.
• $FoxNotifyBodyFmt - body of message to be sent. The string '$FoxNotifyItems' is replaced with the list of posts in the email.
• $FoxNotifyBodyHeadingFmt - heading of body to be sent (top of body, above items).
• $FoxNotifyItemFmt - the default format for each post to be included in a notification.
• $FoxNotifyTemplatePageFmt - name of email template page.
• $FoxNotifyTimeFmt - the format for dates and times ($PostTime) in notification messages.
• $FoxNotifyHeaders - any additional message headers to be sent.
• $FoxNotifyParameters - any additional parameters to be passed to PHP's mail() function.
• $EnableFoxNotifyHTMLEmail = 1; - (default is 0) email will be HTML formatted, wiki markup can be used in email template and form input for email body.
• $FoxNotifyDebug = 1; - (Default is 0) enable debug runs without sending emails.

Using a Fox form to add email addresses to a list

Security note: use this only if you can trust the group of users being able to post email addresses to a list. Do not use it in a wiki where all pages can be edited by anyone (i.e. publically open wiki).

Form to add email addresses example:

This lets users add email addresses to ListA. They can choose the format of the email notification:
Either a single line link (#basic), a link with the topic name added (#topic), or a link with both topic name and full content of post added (#comment).

(:foxmessage:) 
(:fox addemail target="FoxNotifyLists.ListA":)
(:input default nfmt basic :)
Send notifications as single line page links (:input radio nfmt #basic :)\\
Send notifications with topic name only (:input radio nfmt #topic :)\\
Send notifications with full post content (:input radio nfmt #comment :)\\
Send notifications only once per day (:input checkbox squelch 86400:)\\
Add email address for notifications (:input text email:)\\
Author name: (:input text author {$Author}:)
(:input submit post Enter:)
(:foxtemplate " notify={$$email} recipient='{$$author}' format={$$nfmt} squelch={$$squelch} <<< 
 >>> (:if expr ( auth admin OR author {$Author} ):){[foxdelline]}(:if:)":)
(:foxend addemail:)

Notes

• foxnotify.php is substantially built on scripts/notify.php, to preserve much if not all of notify.php's capabilities. I added multiple list handling, notifying a specific list(s) when posting with a form, templates for email formats and use of replacement variables in templates.
• foxnotify.php can work side-by-side with notify.php, or replace and extend its function. Thanks Pm for the excellent notify.php script!

Release Notes

• 2023-09-30: Added $MailFunction for optional use of other mail function than PHP mail().
• 2023-09-28: Added $MailSalutation, Changed $FoxRecipient to $MailRecipient. Added variable replacing in #heading template section.
• 2023-09-27: Added $FoxNotifyDebug variable for easier debugging. Small reformatting.
• 2023-09-26: fixed bug preventing variable replacement in email subject template.
• 2023-01-30: update for PHP 8 compatibility.
• 2015-11-17: fixed another warning error.
• 2015-10-29: fixed warning error in handling foxmail notification (update fox.php too).
• 2010-03-10: Fixed $WikiTitle for subject.
• 2008-09-29: Added capability to use replacement variables of type {$$varname} in email template subject section.
• 2008-05-19: Added option to output HTML formatted messages, by setting $EnableFoxNotifyHTMLEmail = true; Removed foxfilter 'FoxNotify', this is now integrated in fox.php
• 2008-05-17: Added missing linebreak after $FoxNotifyBodyHeadingFmt. Added exemptions for notify check for actions foxpost, foxdelete, comment, in addition to action edit.
• 2008-02-07: Changed inclusion in $EditFunctions to be compliant with standard handling of edit functions.
• 207-10-15: Added #default format option. If no format= or template= string is provided foxnotify will look for #default section on template page, only if that is missing it will load the default from $FoxNotifyItemFmt. Enabled to mail directives of form (:..:) in posts without syntax being garbled
• 2007-1005: Added capability to use email templates from a FoxNotifyTemplates page. Replacement variables of form {$$varname} will get replaced by values of corresponding input form name. Added recipient= parameter for Notify lists, which can be inserted in email body in place of a $FoxRecipient string (default is 'Mail Recipient')
• 2007-10-04a: fixed bug for squelch handling
• 2007-10-04: Initial release

See Also

• PmWiki.Notify
• Fox
• FoxForum

Contributors

• HansB