PmWiki | Cookbook / MailListForm

Summary: Form for subscription to an email list

Version: 2008-08-28

Prerequisites: PmWiki 2.0 or greater

Status: working

Maintainer: Diafygi

Categories: Forms

Question

How can users subscribe to a mailing list?

Answer

Add a form to the wiki for users to fill out and subscribe or unsubscribe.

Description

This is a heavily modified form of the MailForm recipe. It will generate a form on the wiki page and allow users to submit

Requirements:

Your email list software accepts subscriptions via email
Sendmail access for php (ask your admin), allows php to send emails

Installation

download the latest emaillistform.php Δ to your /cookbook directory
add the following lines to your 'config.php' file in your local directory, customizing the variables as you need to:

           include_once('cookbook/emaillistform.php');
           $EMailListFormAddresses['foo'] = 'foo_list@foo.com';
           $EMailListFormAddressesUnSubscribe['foo'] = 'foo_list-unsub@foo.com'; #Optional
           $EMailListFormSubscribeText['foo'] = 'subscribe $EMailListFormName';
           $EMailListFormUnSubscribeText['foo'] = 'unsubscribe $EMailListFormName';
           $EMailListFormSubscribeSubject['foo'] = 'Sign Me Up!';
           $EMailListFormUnSubscribeSubject['foo'] = 'Take Me Off!';

add the following markup for the form to your wiki page:

           emaillistform:foo

This creates a form in the wiki page that will ask for a user's name, email, and whether they want to subscribe or unsubscribe. The recipe will send a message to the email list server according to the variables listed in the config file. For example, if Bob Smith (bobsmith@example.com) subscribed to the above form, it would send the following email:

           From: bobsmith@example.com
           To: foo_lists@foo.com
           Subject: Sign Me Up!
           Message: subscribe Bob Smith

Because variables are identified by their list, you can have many different subscription forms (i.e. foo1, foo2, foo3, etc.). This recipe can be used in addition to other recipes, such as Mail Form, without conflict.

Variables

$EMailListFormAddresses['foo']

The place you want the emails to be sent. Can be multiple emails, separated by commas.

$EMailListFormAddressesUnSubscribe['foo']

New Feature as of 2008-08-28! Backwards Compatible!

The place you want the emails to be sent for unsubscribe emails. This is an optional variable. If no variable is found, the recipe simply uses the subscribe email (i.e. $EMailListFormAddresses['foo']). Can be multiple emails, separated by commas.

$EMailListFormSubscribeText['foo']

What is sent in the body of the email for subscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

$EMailListFormUnSubscribeText['foo']

What is sent in the body of the email for unsubscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

$EMailListFormSubscribeSubject['foo']

What is sent in the subject of the email for subscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

$EMailListFormUnSubscribeSubject['foo']

What is sent in the subject of the email for unsubscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

Internationalizations

These variables can be added in your config.php to allow the form to be used for multiple languages. Currently, this recipe only comes with English, so you do not need to add these variables.

                 $XL['en']['EMLFsuccess'] = 'Message has been sent successfully.';
                 $XL['en']['EMLFfailure'] = 'Message could not be sent.';
                 $XL['en']['EMLFerror']   = 'An error has occurred.';
                 $XL['en']['Your Name'] = 'Your Name';
                 $XL['en']['Your Email'] = 'Your Email';
                 $XL['en']['Submit'] = 'Submit';
                 $XL['en']['Subscribe'] = 'Subscribe';
                 $XL['en']['Unsubscribe'] = 'Unsubscribe';

Custom format

You can create your own custom format for the form by adding the $EMailListFormFmt variable in your 'config.php' file. This is an html variable, so you can't use markup. You must have the following names for inputs on the custom form:

                 emaillistform_address  (hidden, with a value of '$1')
                 action                 (hidden, with a value of 'emaillistform')
                 emaillistform_name     (text, user's name input)
                 emaillistform_sender   (text, user's email input)
                 emaillistform_subscribe
                        (can be radio, or hidden, with value's of 'subscribe' or 'unsubscribe')

POST the form to the same page (i.e. <form action='\$PageUrl' method='post'> )
You can also include $EMailListFormResult in the format to show results/errors.
$1 is the name of the form (i.e. 'foo')

What it looks like:

Notes

Restrictions: You can't create multiple emaillistforms on the same page.
Valid XHTML 1.0 Transitional
Released under GPL

Release Notes

2007-07-12 Released 0.1 -Diafygi
2007-07-15 Released 0.1.1 -added variable for RecipeCheck -Diafygi
2008-08-28 Released 0.2 - added unsubscribe email address variable (as requested by CarneiroTim) -Diafygi

Comments

CarneiroTim (2007-09-28): I would like this script to send a subscription mail to "mailinglist-subscribe@list.com" or an unsubscription mail to "mailinglist-UNsubscribe@list.com". Is that possible or can the subscription/unsubscription only be done by a different subject line?

Thanks for the important feature suggestion. It was not possible before, but I just added a variable that would allow that (see description). The new version should also be backwards compatible with earlier config.php files.-Diafygi (2008-08-28)

Contributors

Diafygi

MailListForm