Mail Notification

Questions answered by this recipe

• How can I add email notification to Fox when posting 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 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 eamil template and input boxes will be rendered as HTML for the email message body.

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

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.

Using foxnotify in a fox form

Add the following to your fox form:

1. Add FoxNotify to the foxfilter functions called by adding it to a hidden foxfilter field. no longer needed
2. Add the name of a notification list (a list page in the FoxNotifyLists group) as value to a foxnotify field. 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":)

Using (:foxmail ....:) or foxaction=mail

The target page (as notify list page) 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.

In both cases you do NOT need (:input hidden foxfilter FoxNotify:)!

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 foxsuccess='E-mail sent successfully!':)
(:foxmail template=FoxNotifyLists.MailFormTemplate target=FoxNotifyLists.EmailList :)
(: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).

Example MailFormTemplate:

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

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

!!Email item formats
[[#default]]
Sent: $PostTime 
Name:    
E-Mail: 
Subject: 



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

Parameters for use in the NotifyList pages

• notify=email-address - essential
• 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.

Using the GeneralNotifyList for notifications

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.

Using config.php to add 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:

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).

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= recipient='' format= squelch= <<< 
 >>> (:if expr ( auth admin OR author {$Author} ):){[foxdelline]}(:if:)":)
(:foxend addemail:)

Using FoxNotifyTemplates

A page called FoxNotifyTemplates in the FoxNotifyLists group can be created to provide templates for the email formatting. Here is an example page:

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

!!Email body heading format
[[#heading]]
Dear Mail Recipient
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: 
[[#topicend]]

!!!#comment
[[#comment]]
$ScriptUrl/$FullName
Author: $LastModifiedBy   posted on $PostTime 
Topic: 
=========================


=========================
[[#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). Mail Recipient will be replaced by the value from the recipient= parameter from each notify list line, or left unchanged.
• 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 , 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 you want HTML formatted messages, set in config.php

and use appropiate wiki markup in the email template (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.

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

• 2015-10-29: fixed warning error in handling foxmail notification (update fox.php too).
• 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 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?