Fox Notify

Summary: add email notifications and mailing capability to Fox forms
Version: 2008-05-19
Prerequisites: PmWiki 2.2.0-beta, Fox > 2008-05-19
Status: new, experimental, please provide feedback!
Maintainer: HansB?
Categories: Forms Fox
Download: Attach:foxnotify.php Δ

Questions answered by this recipe

Description

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

include_once("$FarmD/cookbook/foxnotify.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: {$$name}   
E-Mail: {$$email}
Subject: {$$subject}

{$$text}

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

Parameters for use in the NotifyList pages

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

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:

$FoxNotifyList[] = "notify=name@example.com recipient='Some One'";

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={$$email} recipient='{$$author}' format={$$nfmt} squelch={$$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: {$$topic}
[[#topicend]]

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

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 you want HTML formatted messages, set in config.php

$EnableFoxNotifyHTMLEmail = true;

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

See Also

Contributors